Skip to content
BranchesTags

Repository files navigation

LootVenture mini-app

A blockchain-based challenge and reward mini-app built for the Farcaster social network. Users can set challenges to each other and earn loot rewards through social interactions.

Tech Stack

  • Framework: Next.js with React 19.2
  • UI Library: shadcn/ui
  • CSS Library: TailwindCSS
  • Blockchain Integration:
    • OnchainKit (Base)
    • MiniKit (Farcaster integration)
    • Farcaster sdk (for custom Farcaster integration not available in MiniKit)
    • Wagmi (Ethereum interactions not available in OnchainKit or MiniKit)
  • Smart Contracts: Challenge contract located in ../lootventure-contracts/src/Challenges.sol

Features

  • Create challenge by adding description and transferring tokens for loot rewards
    • Challenge creator also sets completion deadline and optional users for closed user group challenge
    • Challenge creator can set optional verification contract for rules of completion verification process and selection of valid completions
    • Rewards can be in form of native token, ERC20, ERC721 or ERC1155 NFTs
    • After creating the challenge users publish link to challenge on their Farcaster profile
  • From challenge link users can complete the challenge by sending completion url
    • link opens completion form where user can reference Farcaster post url or publish new post and use its url for completion
  • Users can see list of their challenges
  • Users can call smart contract method to payout loot rewards and post to their Farcaster profile

Implementation

  • Farcaster mini-app integration
  • Wallet connectivity via MiniKit and OnchainKit
  • Responsive UI with shadcn components

Configuration

Environment Variables Overview

The application uses environment variables to configure blockchain connectivity, smart contract addresses, and API keys. Configuration is managed through two main files:

  • .env - Committed to git, contains production-safe defaults
  • .env.local - Git-ignored, contains developer-specific overrides and secrets
  • .env.example - Committed to git, serves as documentation template

Priority: .env.local > .env

The committed defaults in this repository point to the shared Reef testnet deployment so the app can boot without extra setup.

Blockchain Configuration

The application supports multiple blockchain networks through environment variables:

Environment Variable Description Required Default
NEXT_PUBLIC_CHAIN_IDENT_NAME Chain identifier (BASE_MAINNET, BASE_SEPOLIA, LOCALHOST, REEF_TESTNET) Yes REEF_TESTNET
NEXT_PUBLIC_RPC_URL Custom RPC endpoint URL No CDP Node (if API key set)
NEXT_PUBLIC_ONCHAINKIT_API_KEY Coinbase Developer Platform API key No -
NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS Deployed Challenges contract address Yes -
NEXT_PUBLIC_CHALLENGES_CONTRACT_DEPLOYMENT_BLOCK Block number where the contract was deployed No 53812
NEXT_PUBLIC_VERIFIED_CONTRACTS JSON array of known verifier contracts for UI display No Reef verifier list

Supported Chains

Chain Identifier Chain ID Default RPC URL Use Case
Reef Testnet REEF_TESTNET 13939 http://eth.reeftestnet1-reefdevcluster-f70119-72-60-35-83.traefik.me/ Shared deployed environment
Localhost (Anvil) LOCALHOST 31337 http://localhost:8545 Local development
Base Sepolia BASE_SEPOLIA 84532 https://sepolia.base.org Testnet testing
Base Mainnet BASE_MAINNET 8453 https://mainnet.base.org Production

Shared Reef Testnet Setup

The committed .env already points to the live Reef testnet deployment:

NEXT_PUBLIC_CHAIN_IDENT_NAME=REEF_TESTNET
NEXT_PUBLIC_RPC_URL=http://eth.reeftestnet1-reefdevcluster-f70119-72-60-35-83.traefik.me/
NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS=0xF1F7ef041e0602C40B1F92d41afe6A4C9E114027
NEXT_PUBLIC_CHALLENGES_CONTRACT_DEPLOYMENT_BLOCK=53812

You can run the app directly with:

npm run dev

Local Development Setup

For local development with Anvil, create .env.local to override the committed Reef defaults:

  1. Copy .env.example to .env.local:

    cp .env.example .env.local

  2. Configure .env.local for localhost:

    # Chain Configuration
NEXT_PUBLIC_CHAIN_IDENT_NAME=LOCALHOST
NEXT_PUBLIC_RPC_URL=http://localhost:8545

# Contract address will be auto-generated by start-contracts.sh
NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS=0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512

  3. Start Anvil and deploy contracts (see Getting Started below)

Testnet Deployment (Base Sepolia)

For testing on Base Sepolia testnet:

  1. Deploy contracts to Base Sepolia testnet

  2. Update .env.local:

    NEXT_PUBLIC_CHAIN_IDENT_NAME=BASE_SEPOLIA
NEXT_PUBLIC_RPC_URL=https://sepolia.base.org
NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS=0xYourSepoliaContractAddress
NEXT_PUBLIC_ONCHAINKIT_API_KEY=your_api_key_here

  3. Get testnet ETH from a Base Sepolia faucet

  4. Test your application on the testnet

Alternative RPC Providers:

  • Alchemy: https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY
  • Infura: https://base-sepolia.infura.io/v3/YOUR_API_KEY

Production Deployment (Base Mainnet)

For production deployment on Base mainnet:

  1. Deploy contracts to Base mainnet

  2. Set environment variables in your hosting platform (e.g., Vercel):

    NEXT_PUBLIC_CHAIN_IDENT_NAME=BASE_MAINNET
# Leave NEXT_PUBLIC_RPC_URL unset to use CDP Node
NEXT_PUBLIC_ONCHAINKIT_API_KEY=your_production_api_key
NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS=0xYourMainnetContractAddress

  3. Alternatively, use a custom RPC provider:

    NEXT_PUBLIC_CHAIN_IDENT_NAME=BASE_MAINNET
NEXT_PUBLIC_RPC_URL=https://mainnet.base.org
# Or: https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY
# Or: https://base-mainnet.infura.io/v3/YOUR_API_KEY
NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS=0xYourMainnetContractAddress

Getting API Keys

Coinbase Developer Platform (CDP):

  1. Visit CDP Portal
  2. Create a project
  3. Copy your API key to NEXT_PUBLIC_ONCHAINKIT_API_KEY

Alchemy:

  1. Visit Alchemy
  2. Create an app for Base network
  3. Copy the API key from your app dashboard

Infura:

  1. Visit Infura
  2. Create a project and add Base network
  3. Copy the project ID

Troubleshooting

Chain ID mismatch error:

  • Ensure your wallet is connected to the same network as NEXT_PUBLIC_CHAIN_IDENT_NAME
  • Switch your wallet network or update the chain identifier in .env.local

Cannot connect to RPC:

  • For localhost: Ensure Anvil is running (./_dev-scripts/start-contracts.sh)
  • For remote: Verify RPC URL is correct and accessible
  • Check that API keys are valid and not expired

Contract not found error:

  • Verify NEXT_PUBLIC_CHALLENGES_CONTRACT_ADDRESS matches the configured chain
  • Ensure contracts are deployed to the correct network
  • Check contract address format (should start with 0x)

Environment variables not updating:

  • Restart dev server after changing .env.local: npm run dev
  • For production builds, rebuild with npm run build
  • Next.js caches environment variables at build/start time

Getting Started

1. Get Git submodules by running ./_dev-scripts/update-submodules.sh

2. Install dependencies in submodules by running npm i in lootventure-contracts submodule

3. Start local node with deployed contracts by running ./_dev-scripts/start-contracts.sh.

This will also generate ./_dev-scripts/.env-contracts file with deployed contract addresses.

4. Install nextjs dependencies:

# install nextjs mini-app
npm install

5. Run nextjs mini-app development server with ./_dev-scripts/.env-contracts env variables:

npm run dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

6. (Optional) Configure Custom RPC Endpoint

By default, the application uses Coinbase Developer Platform's Node (CDP Node) for blockchain requests, which requires the NEXT_PUBLIC_ONCHAINKIT_API_KEY environment variable. However, you can configure a custom RPC endpoint using the NEXT_PUBLIC_RPC_URL environment variable.

When to Use Custom RPC URL

  • Local development: Connect to your local Anvil node started by ./_dev-scripts/start-contracts.sh
  • Custom RPC providers: Use premium or private RPC endpoints (Alchemy, Infura, Ankr, etc.)
  • Development/testing: Point to different network environments

Configuration

Edit .env.local and add or uncomment the NEXT_PUBLIC_RPC_URL variable:

For local development with Anvil:

NEXT_PUBLIC_RPC_URL=http://localhost:8545

For production with custom RPC providers:

# Base public RPC
NEXT_PUBLIC_RPC_URL=https://mainnet.base.org

# Alchemy
NEXT_PUBLIC_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY

# Infura
NEXT_PUBLIC_RPC_URL=https://base-mainnet.infura.io/v3/YOUR_API_KEY

RPC Behavior

  • When NEXT_PUBLIC_RPC_URL is set: OnchainKitProvider uses the custom RPC endpoint
  • When NEXT_PUBLIC_RPC_URL is not set: Falls back to CDP Node (requires NEXT_PUBLIC_ONCHAINKIT_API_KEY)
  • Chain compatibility: The RPC URL must match the configured chain (Base network)

After changing the RPC URL, restart the development server for changes to take effect.

Documentation

The ai-docs directory contains comprehensive documentation and best practices organized by technology:

ai-docs Structure

  • farcaster/ - Farcaster mini-app integration

    • Authentication, navigation, wallet integration
    • Mini-app context, notifications, and events
    • Publishing and discovery guidelines
    • SDK API reference and share extensions

  • mini-app/ - General mini-app development

    • Context and navigation patterns
    • Design guidelines and best practices
    • Embeds, previews, and notifications
    • Wagmi wallet integration

  • nextjs/ - Next.js framework patterns

    • Project structure and file system
    • Layouts, pages, and routing
    • Server and client components
    • Data fetching and caching strategies
    • Error handling

  • onchain-kit/ - OnchainKit components and utilities

    • Provider setup and configuration
    • Transaction components
    • MiniKit hooks (authentication, notifications, etc.)
    • Theming and formatting utilities

  • react-19.2/ - React best practices

    • Hooks reference (useState, useEffect, etc.)
    • Components (Suspense, Fragment, etc.)
    • Design patterns and TypeScript usage
    • State management and component purity

  • shadcn-ui-lib/ - shadcn UI component library

    • Complete component reference
    • Installation and configuration
    • Theming and dark mode
    • React Hook Form integration

  • wagmi/ - Wagmi blockchain interactions

    • React hooks for contract interactions
    • Reading from and writing to contracts
    • Transaction handling and chain queries
    • Error handling and TypeScript support

External Resources

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages