Junkyard Arcade | Turn meme dust into verifiable blind boxes.

Introduction

Project Introduction

Junkyard Arcade is a full-stack onchain blind box system built around verifiable randomness, multi-asset prize pools, and an operator-friendly web console.

What the project is

The protocol packages token dust, NFTs, and mixed inventories into blind box series. Creators launch a series contract, fund a prize pool, and let collectors buy, open, and claim through a single product surface.

The repository is split into three layers: Foundry contracts for protocol rules, a Graph subgraph for indexed state, and a Next.js 15 frontend for the operator and collector experience.

Stack at a glance

Contracts: Solidity + Foundry for factory, series, prize pool, and oracle integrations.
Indexer: The Graph subgraph for series, blind box, asset, and transaction state.
Frontend: Next.js 15 App Router, React 19, wagmi, RainbowKit, shadcn/ui.

Current product constraints

The current creator flow is intentionally constrained: Base Sepolia only, preset factory/oracle wiring, and a UI that optimizes clarity over protocol breadth.

Setup

Quick Start

The shortest path to run the workspace locally and validate that contracts, subgraph, and frontend are wired together.

1. Install dependencies

pnpm install

2. Prepare frontend environment values

Copy the example env for the web app and fill in the subgraph endpoint plus Base Sepolia factory/oracle presets.

cp apps/web/.env.example apps/web/.env.local

3. Validate protocol and indexer layers

pnpm --dir apps/contracts test
pnpm --dir apps/subgraph codegen
pnpm --dir apps/subgraph build

4. Start the frontend

pnpm --dir apps/web graphclient:build
pnpm --dir apps/web dev

Features

Core Features

The protocol is opinionated in the places where launch mistakes are expensive and flexible where creators need room to design drops.

Verifiable randomness

Blind boxes remain unresolved until the oracle fulfills randomness. That keeps prize assignment hidden before opening and removes the need for offchain reveal scripts.

Mixed reward inventory

ERC20 balances for token-style prizes.
ERC721 collectibles for single-item rewards.
ERC1155 balances for semi-fungible prize buckets.

Operational controls

Creators can update sale settings within protocol limits, configure leftover handling, and manage reward inventory from the admin dock on the series detail page.

Lifecycle

Blind Box Lifecycle

From deployment to leftover cleanup, the protocol separates each stage so the system stays auditable and operationally clear.

1. Deploy the series

The factory creates a new series contract with the chosen name, symbol, supply cap, sale window, payment asset, and guard/oracle presets.

2. Fund the prize pool

The series owner initializes reward assets, whitelists them, approves transfers, and deposits inventory into the prize pool before the drop goes live.

3. Buy, open, and claim

Collectors purchase a blind box NFT, request randomness to open it, and claim after fulfillment resolves the prize outcome.

4. Handle leftovers

After the series ends and claims settle, the owner can execute the configured leftover strategy against remaining assets.

Guide

Creator Workflow

How a creator launches, funds, monitors, and closes a blind box series using the current frontend.

Create a series

Open /create and connect the creator wallet.
Fill name, symbol, supply cap, price, and sale window.
Submit the deployment transaction and wait for redirect to the new series detail page.

Fund rewards

Use the admin tabs on the series detail page to whitelist reward assets and deposit ERC20, ERC721, or ERC1155 inventory.

Manage live operations

Track sales and claims from /series and the series detail dashboard. If needed, tighten the sale window or apply leftover policy after the campaign ends.

Guide

Collector Workflow

How a player discovers a drop, buys a box, opens it, and claims the final reward.

Discover a drop

Browse /series to compare active drops, supply pressure, and sale windows before entering a specific series.

Buy a blind box

Open the target series detail page, connect a wallet, and purchase from the action dock. The box is minted directly into the connected wallet.

Open and claim

Use the owned blind box shelf on the series detail page or /me to request opening. Return after fulfillment to claim the reward and close the box lifecycle.

Reference

Configuration Reference

The minimal environment values required for the current Base Sepolia deployment path and frontend experience.

Important environment values

NEXT_PUBLIC_SITE_URL: canonical host for metadata and sitemap.
SUBGRAPH_URL / NEXT_PUBLIC_SUBGRAPH_URL: indexed data endpoint.
NEXT_PUBLIC_FACTORY_SEPOLIA: factory preset used by the create flow.
NEXT_PUBLIC_DEFAULT_ORACLE_SEPOLIA: default Chainlink VRF preset exposed in the create form.

Example

NEXT_PUBLIC_SITE_URL=http://localhost:3000
SUBGRAPH_URL=http://localhost:8000/subgraphs/name/junkyard
NEXT_PUBLIC_SUBGRAPH_URL=http://localhost:8000/subgraphs/name/junkyard
NEXT_PUBLIC_FACTORY_SEPOLIA=0x...
NEXT_PUBLIC_DEFAULT_ORACLE_SEPOLIA=0x...

Notes

The frontend create flow is intentionally fixed to Base Sepolia today. If production networks are added later, this page should expand alongside the preset system.

Project Documentation