Skip to content

QUICKSTART.md

Latest commit

 

History

History
282 lines (208 loc) · 6.08 KB

QUICKSTART.md

File metadata and controls

282 lines (208 loc) · 6.08 KB
Raw

🚀 VaultGuard - Quick Start Guide

Overview

VaultGuard is a decentralized bug bounty platform featuring:

  • Protocol-friendly: Custom payout tiers and judge selection
  • Researcher-friendly: Transparent, automatic payouts (2.5% fee)
  • Judge-based verification: Multisig voting system

📋 Prerequisites

Before you begin, ensure you have:

  • Node.js (v20 or higher)
  • pnpm (recommended) or npm
  • MetaMask or another Web3 wallet
  • Basic understanding of Web3/Ethereum

🏃 Quick Start

1. Clone the Repository

git clone https://github.com/Gbangbolaoluwagbemiga/GuidlVault.git
cd GuidlVault

2. Install Dependencies

For the entire project:

npm install

For frontend only:

cd frontend
pnpm install
# or
npm install

3. Configure Environment (Optional)

Create .env.local in the frontend directory:

NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your_project_id_here

Get your project ID from WalletConnect Cloud

4. Start the Development Server

# From the frontend directory
pnpm dev
# or
npm run dev

The app will be available at http://localhost:3000

🌐 Network Configuration

Celo Mainnet

Base Mainnet

🎮 User Flows

For Protocol Owners

  1. Connect Wallet (top right)
  2. Navigate to Create Vault
  3. Fill in the form:
    • Initial deposit (CELO)
    • Add judge addresses
    • Set required approvals
    • Configure payout percentages
  4. Submit transaction
  5. Wait for confirmation
  6. Your vault is now live!

For Security Researchers

  1. Connect Wallet
  2. Browse Vaults to find active bounties
  3. Navigate to Submit
  4. Select a vault
  5. Enter IPFS hash of your report
  6. Select severity level
  7. Submit transaction
  8. Track your submission in the Dashboard
  9. Claim payout once approved

For Judges

  1. Connect Wallet
  2. Navigate to Judge Portal
  3. Review pending submissions
  4. Read vulnerability reports (via IPFS hash)
  5. Vote to Approve or Reject
  6. Transaction confirms your vote

📁 Project Structure

GuidlVault/
├── contracts/              # Solidity smart contracts
│   └── VaultGuard.sol     # Main contract
├── frontend/              # Next.js frontend
│   ├── app/              # Pages (Next.js 15 App Router)
│   ├── components/       # Reusable components
│   ├── hooks/           # Custom React hooks
│   ├── lib/             # Utilities and config
│   └── public/          # Static assets
├── scripts/             # Deployment scripts
├── test/               # Contract tests
└── hardhat.config.js   # Hardhat configuration

🛠️ Development Commands

Frontend

# Development server
pnpm dev

# Production build
pnpm build

# Start production server
pnpm start

# Lint code
pnpm lint

Smart Contracts

# Compile contracts
npm run compile

# Run tests
npm run test

# Deploy to Celo Mainnet
npm run deploy:celo:mainnet

# Deploy to Celo Alfajores (Testnet)
npm run deploy:celo:alfajores

🎨 Key Features

✨ Modern UI

  • Glassmorphism design
  • Dark mode support
  • Smooth animations
  • Responsive layout

🔐 Security

  • Type-safe contract interactions
  • Form validation
  • Error boundaries
  • Transaction confirmations

🚀 Performance

  • Code splitting
  • Optimized bundle size
  • Skeleton loading screens
  • Efficient re-renders

📚 Tech Stack

Frontend

  • Framework: Next.js 15
  • UI: React 19, TailwindCSS
  • Web3: Wagmi, Viem, Ethers.js
  • Animations: Framer Motion
  • Components: Radix UI, shadcn/ui

Smart Contracts

  • Language: Solidity
  • Framework: Hardhat
  • Testing: Chai, Hardhat Network Helpers

🔧 Customization

Update Contract Address

Edit frontend/lib/contract.ts:

export const VAULT_GUARD_ADDRESS = "0xYourNewAddress";

Change Theme Colors

Edit frontend/app/globals.css:

:root {
  --primary: 222.2 47.4% 11.2%;
  --secondary: 210 40% 96.1%;
  /* ... other colors */
}

Add Custom Network

Edit frontend/lib/wagmi.tsx:

const config = createAppKit({
  // ... existing config
  networks: [celo, base, yourCustomNetwork],
  // ...
});

🐛 Troubleshooting

Wallet Connection Issues

  • Ensure MetaMask is installed
  • Check you're on the correct network (Celo or Base)
  • Try disconnecting and reconnecting

Transaction Failures

  • Check you have enough CELO/ETH for gas
  • Verify contract addresses are correct
  • Check network connection

Build Errors

  • Delete node_modules and reinstall
  • Clear Next.js cache: rm -rf .next
  • Verify Node.js version (v20+)

📖 Additional Resources

Documentation

Links

🤝 Contributing

We welcome contributions! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

📄 License

MIT License - see LICENSE file

💬 Support

Happy Hacking! 🎉

Built with ❤️ for the Web3 security ecosystem