Skip to main content
</>Vibecode Bible

CLAUDE.md — OPNet Full-Stack Project

This file tells Claude everything it needs to know about this project.

#What This Is

A full-stack OPNet application. AssemblyScript smart contracts on Bitcoin L1, a React frontend with OPWallet integration, and a backend service for any off-chain logic.

#Plugin Setup

This project uses the buidl-opnet-plugin. To start Claude with the plugin loaded:

bash
# Add these aliases to your shell config (~/.bashrc or ~/.zshrc):
alias claudey="claude --plugin-dir /path/to/buidl-opnet-plugin/buidl"
alias claudeyproj="claude --dangerously-skip-permissions --plugin-dir /path/to/buidl-opnet-plugin/buidl"

Use claudeyproj for autonomous builds with the /buidl command.

When the plugin is loaded, Claude has access to all 8 specialized agents:

  • opnet-contract-dev — AssemblyScript contracts
  • opnet-frontend-dev — React frontend with wallet integration
  • opnet-backend-dev — backend services (hyper-express)
  • opnet-auditor — 27 real-bug audit patterns from btc-vision repos
  • opnet-deployer — testnet and mainnet deployment
  • opnet-e2e-tester — end-to-end test suite
  • opnet-ui-tester — frontend interface testing
  • loop-reviewer — final review before marking complete

The /buidl command runs the full pipeline automatically.

#Project Structure

text
/
├── contracts/          # AssemblyScript smart contracts
│   ├── src/
│   └── build/
├── frontend/           # React frontend
│   ├── src/
│   └── public/
├── backend/            # Backend service (hyper-express)
│   └── src/
└── CLAUDE.md           # This file

#Project Details

App name: [Your App Name] Contract address: [deployed contract address — fill in after deployment] Network: [testnet / mainnet] Backend URL: [http://localhost:3000 or deployed URL]

#What This App Does

[Describe the app in 2-3 sentences]

#Core User Flow

[Describe the main thing a user does, step by step]

  1. [step 1]
  2. [step 2]
  3. [step 3]

#Smart Contracts

Contract: [Name] Standard: [OP20 / OP721 / custom] Key functions:

  • [function]: [what it does]
  • [function]: [what it does]

Security requirements:

  • All u256 arithmetic uses SafeMath
  • Storage pointers are unique (see storage layout below)
  • No while loops
  • CSV timelocks on swap addresses

#Frontend

Framework: React + TypeScript Wallet: OPWallet (signer always null in frontend — wallet extension signs) Design: Dark theme, OPNet orange (#F7931A) accent, production-quality DeFi aesthetic

#Backend

Framework: hyper-express (required — never Express/Fastify/Koa) Purpose: [what the backend handles — indexing, off-chain data, notifications, etc.] Port: 3000

#Build Commands

bash
# Contracts
cd contracts && npm run build
cd contracts && npm run test
cd contracts && npm run deploy:testnet

# Frontend
cd frontend && npm run dev
cd frontend && npm run build

# Backend
cd backend && npm run dev
cd backend && npm run start

#Using the /buidl Pipeline

For the initial build or major new features, use the full pipeline from the project root:

text
/buidl "describe the feature or full app"

The pipeline will build contracts, frontend, and backend in the correct order (contracts first, then frontend+backend in parallel), then audit, deploy, and test.

For targeted changes after the initial build, use direct prompts.

#Deployment

Contracts: Deploy via deployer agent or npm run deploy:mainnet in contracts/

Frontend:

bash
# .btc domain (recommended)
opnet deploy your-domain ./frontend/dist

# Vercel
cd frontend && vercel

# IPFS
cd frontend && npm run build
# upload ./dist to IPFS

Backend: Deploy to your preferred hosting (VPS, Railway, Fly.io, etc.)

#Storage Layout (Contracts)

Slot Name Type Description
1
2

#Environment Variables

bash
# frontend/.env
VITE_CONTRACT_ADDRESS=
VITE_NETWORK=testnet
VITE_BACKEND_URL=http://localhost:3000

# backend/.env
NETWORK=testnet
RPC_URL=https://regtest.opnet.org
PORT=3000

Ready to test your knowledge?

20 questions covering everything from vibecoding basics to shipping a complete dApp.

Take the Quiz