Bun-Eth

A Bun-first scaffold for Ethereum projects

A pure Bun-native monorepo template for building Ethereum-based applications. Replace scaffold-eth-2's Node/React stack with a modern, TypeScript-first approach using Bun, Elysia, and Foundry.

✨ Features

🔥 Contract Hot Reload - Your frontend auto-adapts to your smart contracts as you deploy them
🎣 Custom Hooks - Type-safe React hooks for reading, writing, and watching contracts (@bun-eth/hooks)
🧱 Web3 Components - Pre-built UI components for addresses, balances, inputs, and more (@bun-eth/components)
💰 Burner Wallet - Ephemeral wallets for instant testing without MetaMask
🚰 Local Faucet - Built-in faucet for quick testing on Anvil
🌈 RainbowKit - Beautiful wallet connection UI with multi-wallet support
🚀 Bun-Native - 100% Bun, no Node.js required - lightning fast builds
⚡ Elysia Backend - Fast, TypeScript-first web framework for REST API
🎨 Next.js Frontend - Modern React framework with shadcn/ui components
🔨 Foundry Contracts - Blazing fast Rust-based smart contract framework (Forge + Anvil)
🐳 Docker Compose - Complete local development environment
📦 Clean Monorepo - Well-architected packages with clear separation of concerns
🧪 Comprehensive Testing - Bun tests for TypeScript, Foundry tests for Solidity
🔧 Taskfile - Powerful command orchestration
💎 Full TypeScript - Type safety from contracts to UI

🚀 Quick Start

Using the CLI (Recommended)

bunx create-bun-eth@latest my-dapp
cd my-dapp
task setup

Manual Clone

git clone https://github.com/Bun-Eth-Community/bun-eth.git my-dapp
cd my-dapp
task setup

The setup task will:

Create .env from .env.example
Install all dependencies
Compile smart contracts
Run all tests to verify everything works

📋 Prerequisites

Bun >= 1.1.0
Foundry (for smart contracts)
Docker (for local Ethereum node)
Task (optional, for orchestration)

Install Task

# macOS
brew install go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Or use bunx
bunx @go-task/cli

📸 Screenshots

The project includes a stunning 3D animated crowdsale interface with multiple states and responsive design.

Key Features

3D Animated Hero - Eye-catching title with gradient effects and floating particles
Status Indicators - Clear visual feedback for all crowdsale states (not deployed, loading, active, ended)
Real-time Data - Live blockchain data updates with animated stats
Responsive Design - Optimized for desktop, tablet, and mobile devices

View All Screenshots

For detailed screenshots of all UI states, responsive views, and individual sections, see docs/SCREENSHOTS.md.

🏗️ Project Structure

bun-eth/
├── apps/
│   ├── api/                         # Elysia backend API
│   │   ├── src/
│   │   │   ├── index.ts            # API entry point
│   │   │   ├── config.ts           # Configuration
│   │   │   ├── provider.ts         # Ethereum provider setup
│   │   │   └── routes/             # API routes
│   │   └── Dockerfile
│   └── web/                         # Next.js frontend
│       ├── src/
│       │   ├── app/                # App router pages
│       │   ├── components/         # Local components
│       │   └── lib/                # Utilities & wagmi config
│       └── package.json
├── packages/
│   ├── contracts/                   # Smart contracts (Foundry)
│   │   ├── contracts/              # Solidity files
│   │   ├── script/                 # Deploy scripts
│   │   ├── test/                   # Foundry tests
│   │   ├── deployedContracts.ts    # 🔥 Auto-generated (hot reload!)
│   │   └── foundry.toml
│   ├── hooks/                       # 🎣 React hooks for Web3
│   │   └── src/
│   │       ├── useScaffoldContract.ts
│   │       ├── useScaffoldReadContract.ts
│   │       ├── useScaffoldWriteContract.ts
│   │       └── ...                 # 10+ hooks
│   ├── components/                  # 🧱 Web3 UI components
│   │   └── src/
│   │       ├── Address.tsx
│   │       ├── Balance.tsx
│   │       ├── Faucet.tsx
│   │       └── ...                 # 10+ components
│   ├── foundry-deployer/            # 🔥 Hot reload system
│   │   └── src/
│   │       ├── generator.ts        # Generates deployedContracts.ts
│   │       └── cli.ts              # CLI tool
│   ├── core/                        # Shared utilities
│   ├── sdk/                         # TypeScript SDK for API
│   └── create-bun-eth/              # Scaffolding CLI
├── tooling/
│   └── task/
│       └── Taskfile.yml            # Task definitions
└── docker/
    └── docker-compose.yml          # Anvil + API + Web

🛠️ Development

Start Development Stack

task dev:up

This command intelligently starts all services with health checks:

Anvil local Ethereum node on http://localhost:3002
Bun-Eth API on http://localhost:3001
Next.js Web UI on http://localhost:3000

Features:

✅ Verifies each service is actually responding before reporting success
⏳ Shows clear waiting indicators for each service
❌ Exits with error if any service fails to start (with troubleshooting tips)
📍 Only displays service URLs when they're confirmed to be working

The command will:

Start Docker services (Anvil + API)
Start Web dev server
Wait up to 30 seconds for each service to respond
Display success with service URLs, or fail with helpful error messages

Check Service Status

task status

Displays real-time status of all services with health checks:

Shows Docker container status
Tests HTTP endpoints for Web and API
Tests JSON-RPC for Anvil node
Clearly indicates which services are healthy (✅) or not responding (❌)

Start Web UI Only

task web:dev

This starts the Next.js frontend on http://localhost:3000

Stop Development Stack

task dev:down

Stops all services cleanly (Docker containers + Web dev server).

View Logs

# All services
task dev:logs

# API only
task dev:logs:api

# Anvil node only
task dev:logs:anvil

# Web dev server only
task dev:logs:web

📜 Smart Contracts

Compile Contracts

task contracts:compile

Deploy Contracts

# Deploy to local network
task contracts:deploy

# Deploy to Sepolia
task contracts:deploy:sepolia

Test Contracts

task contracts:test

🌐 API Endpoints

Base URL: http://localhost:3001

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": 1234567890,
  "version": "0.1.0",
  "network": {
    "chainId": 31337,
    "blockNumber": 42
  }
}

Get Wallet Info

GET /wallet/:address

Response:

{
  "address": "0x...",
  "balance": "10.5",
  "nonce": 5
}

Send Transaction

POST /wallet/send
Content-Type: application/json

{
  "to": "0x...",
  "value": "1.0",
  "data": "0x..."
}

Call Contract (Read)

POST /contract/call
Content-Type: application/json

{
  "contractAddress": "0x...",
  "method": "retrieve",
  "args": []
}

Send Contract Transaction (Write)

POST /contract/send
Content-Type: application/json

{
  "contractAddress": "0x...",
  "method": "store",
  "args": [42],
  "value": "0"
}

🌐 Frontend Development

The Next.js frontend includes:

shadcn/ui - Beautiful, accessible components built on Radix UI
wagmi - React Hooks for Ethereum
viem - TypeScript Ethereum library
Tailwind CSS - Utility-first CSS framework

Web Tasks

# Start development server
task web:dev

# Build for production
task web:build

# Start production server
task web:start

Wallet Integration

The frontend supports:

MetaMask and other injected wallets
WalletConnect for mobile wallets
Automatic network switching
Real-time blockchain data updates

🧪 Testing

Run All Tests

task test

Run Tests by Package

# Unit tests only
task test:unit

# Contract tests
task test:contracts

# E2E tests (requires dev stack running)
task test:e2e

# API tests
task test:api

# SDK tests
task test:sdk

# Core tests
task test:core

Watch Mode

task test:watch

Coverage

task test:coverage

Generate Test Documentation

task test:docs

This generates comprehensive test documentation in docs/TEST_RESULTS.md with:

Unit test results (TypeScript)
Smart contract test results (Solidity)
Coverage reports for both
Test file inventory

📊 Test Results

For detailed test results and coverage reports, see docs/TEST_RESULTS.md.

Current Test Summary:

Unit Tests: 9 tests passing (TypeScript)
Contract Tests: 35 tests passing (Solidity)
E2E Test Suites: 7 test suites (16+ test cases)
- Contract integration tests
- Purchase flow tests
- Screenshot capture tests
- Wallet connection tests
- Accessibility tests
Total: 60+ tests

Coverage:

Unit Tests: 54.17% functions, 50.26% lines
Contract Tests: 56.44% lines, 50.57% statements
Core Contracts: 100% coverage for RefundableCrowdsale.sol and TimedCrowdsale.sol

E2E Test Requirements:

Dev stack running (task dev:up)
Contracts deployed (task contracts:deploy)
See TEST_RESULTS.md for details

Screenshot Tests: Generate screenshots for all crowdsale states (before opening, active, ended) with time manipulation:

task test:e2e:screenshots

Run task test:docs to regenerate the test documentation with the latest results.

📦 Using the SDK

Install in your project:

bun add @bun-eth/sdk

Usage:

import { createClient } from "@bun-eth/sdk";

const client = createClient({
  baseUrl: "http://localhost:3001",
  timeout: 30000,
});

// Check health
const health = await client.health();

// Get wallet info
const wallet = await client.getWallet("0x...");

// Send transaction
const tx = await client.sendTransaction({
  to: "0x...",
  value: "1.0",
});

// Call contract
const result = await client.contractCall({
  contractAddress: "0x...",
  method: "retrieve",
  args: [],
});

🔧 Configuration

Environment Variables

Copy .env.example to .env and configure:

# Port Configuration (consecutive ports for easy management)
WEB_PORT=3000
API_PORT=3001
ANVIL_PORT=3002

# API Configuration
PORT=3001
NODE_ENV=development

# Ethereum Node
ANVIL_NODE=http://localhost:3002
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# Network Configuration
CHAIN_ID=31337

# Frontend (Optional)
NEXT_PUBLIC_WC_PROJECT_ID=  # WalletConnect Project ID

Foundry Networks

Edit packages/contracts/foundry.toml:

[rpc_endpoints]
localhost = "http://127.0.0.1:8545"
sepolia = "${SEPOLIA_RPC_URL}"

🚀 Quick Start Example

After running task dev:up and task contracts:deploy, use the new packages:

// In your component
import { useScaffoldReadContract, useScaffoldWriteContract } from "@bun-eth/hooks";
import { Address, Balance, FaucetButton, BurnerWalletInfo } from "@bun-eth/components";
import { useAccount } from "wagmi";

function MyDApp() {
  const { address } = useAccount();

  // Read contract state - auto-refreshes on new blocks
  const { data: value } = useScaffoldReadContract({
    contractName: "SimpleStorage",
    functionName: "retrieve",
    watch: true,
  });

  // Write to contract - includes notifications
  const { writeContractAsync, isMining } = useScaffoldWriteContract("SimpleStorage");

  const handleStore = async () => {
    await writeContractAsync("store", [42]);
  };

  return (
    <div>
      {/* Show burner wallet info if using burner */}
      <BurnerWalletInfo />

      {/* Display address with ENS */}
      <Address address={address} format="short" />

      {/* Balance with USD toggle */}
      <Balance address={address} usdMode />

      {/* Faucet for test ETH */}
      <FaucetButton />

      {/* Contract interaction */}
      <p>Stored Value: {value?.toString()}</p>
      <button onClick={handleStore} disabled={isMining}>
        {isMining ? "Mining..." : "Store 42"}
      </button>
    </div>
  );
}

📚 Available Commands

Run task --list to see all available commands.

Essential Commands

# Setup - Complete local setup with tests
task setup

# Start - Quick start dev stack (install, compile, start services)
task start

# Development
task dev:up              # Start local development stack (Anvil + API + Web)
task dev:down            # Stop local development stack
task dev:logs            # View logs from all services

# Frontend
task web:dev             # Start Next.js dev server
task web:build           # Build Next.js for production
task web:start           # Start Next.js production server

# Contracts
task contracts:compile   # Compile smart contracts
task contracts:deploy    # Deploy to local network + generate types (🔥 hot reload)
task contracts:generate  # Generate TypeScript from deployed contracts
task contracts:test      # Run contract tests

# Testing
task test                # Run all tests
task test:core           # Run core utility tests only
task test:sdk            # Run SDK tests only
task test:contracts      # Run contract tests only

# Monitoring
task status              # Show development stack status with health checks
task check:health        # Check API health endpoint (with JSON output)

# Other
task clean               # Clean build artifacts

🚢 Deployment

Deploy to Production

Set environment variables:

export NODE_ENV=production
export PRIVATE_KEY=your_private_key
export SEPOLIA_RPC_URL=your_rpc_url

Deploy contracts:

task contracts:deploy:sepolia

Build and deploy API:

docker build -f apps/api/Dockerfile -t bun-eth-api .
docker run -p 3001:3001 --env-file .env bun-eth-api

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m 'feat: add my feature'
Push to the branch: git push origin feature/my-feature
Open a Pull Request

📚 Documentation

General

FEATURES.md - Complete feature list and comparisons
ARCHITECTURE.md - System design and architecture
QUICKSTART.md - Quick start guide
CONTRIBUTING.md - Contribution guidelines

Crowdsale

CROWDSALE_FEATURES.md - Crowdsale feature documentation
CROWDSALE_INTEGRATION.md - Smart contract integration guide
CROWDSALE_UI.md - UI implementation details
STATUS_INDICATORS.md - Status banner system
DEPLOYMENT_GUIDE.md - Deployment instructions
SCREENSHOTS.md - UI screenshots and states
E2E_TESTS.md - E2E testing documentation
CSS_FIXES.md - CSS troubleshooting

Packages

packages/hooks/README.md - Custom hooks documentation
packages/components/README.md - UI components guide
packages/foundry-deployer/README.md - Hot reload system
packages/burner-connector/README.md - Burner wallet connector

🎓 Learn More

Foundry Book - Learn Foundry
Viem Docs - TypeScript Ethereum library
Wagmi Docs - React Hooks for Ethereum
RainbowKit Docs - Wallet connection UI
Scaffold-ETH 2 - Original inspiration

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Bun - The blazingly fast JavaScript runtime
Elysia - Fast and ergonomic TypeScript web framework
Foundry - Blazing fast Ethereum development toolkit
scaffold-eth-2 - Inspiration for features
wagmi + viem - Modern Ethereum libraries
RainbowKit - Beautiful wallet UX

📞 Support

Built with ⚡ by the Bun-Eth community

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.changeset		.changeset
.claude		.claude
.github/workflows		.github/workflows
apps		apps
docker		docker
docs		docs
packages		packages
scripts		scripts
test/wallet-setup		test/wallet-setup
tooling/task		tooling/task
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
LICENSE		LICENSE
NEXT_STEPS.md		NEXT_STEPS.md
PORT_FIX.md		PORT_FIX.md
README.md		README.md
Taskfile.yml		Taskfile.yml
bunfig.toml		bunfig.toml
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Bun-Eth

✨ Features

🚀 Quick Start

Using the CLI (Recommended)

Manual Clone

📋 Prerequisites

Install Task

📸 Screenshots

Key Features

View All Screenshots

🏗️ Project Structure

🛠️ Development

Start Development Stack

Check Service Status

Start Web UI Only

Stop Development Stack

View Logs

📜 Smart Contracts

Compile Contracts

Deploy Contracts

Test Contracts

🌐 API Endpoints

Health Check

Get Wallet Info

Send Transaction

Call Contract (Read)

Send Contract Transaction (Write)

🌐 Frontend Development

Web Tasks

Wallet Integration

🧪 Testing

Run All Tests

Run Tests by Package

Watch Mode

Coverage

Generate Test Documentation

📊 Test Results

📦 Using the SDK

🔧 Configuration

Environment Variables

Foundry Networks

🚀 Quick Start Example

📚 Available Commands

Essential Commands

🚢 Deployment

Deploy to Production

🤝 Contributing

📚 Documentation

General

Crowdsale

Packages

🎓 Learn More

📄 License

🙏 Acknowledgments

📞 Support

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages