BetVanta Development Guide

This skill provides AI agents with concise, repo-specific instructions for working in the BetVanta codebase—a Web3 betting platform monorepo with Solidity contracts and a Next.js frontend.

Architecture Overview

BetVanta is a monorepo containing:

Core Betting Logic

The bet lifecycle is managed in `contracts/core/BetVantaCore.sol`:

**Events:**

**State Flow:**

**Token Integration:**

Development Workflows

Frontend Development

All frontend commands run from the `frontend/` directory:

```bash

Install dependencies (from repo root)

pnpm -w install

Start development server

pnpm --filter @betvanta/frontend dev

Production build

pnpm --filter @betvanta/frontend build

```

Smart Contract Development

Contracts use Hardhat for compilation and testing:

```bash

Compile contracts

pnpm hardhat compile

Run tests

pnpm hardhat test

```

**Note:** Consider moving Hardhat dependencies under the `contracts/` workspace for better organization.

Shared Library

```bash

Build shared utilities

pnpm --filter @betvanta/shared build

```

Code Conventions

**Path Aliases:**

**Web3 Integration:**

- `frontend/src/hooks/useWeb3.ts` — wallet connection and provider setup

- `frontend/src/hooks/useBetting.ts` — betting contract interactions

**Forms:**

Known Issues & Integration Gotchas

1. Ethers.js Version Mismatch

**Problem:** Code uses ethers v5 patterns but packages declare v6 dependencies.

**V5 Patterns Found:**

```typescript

ethers.providers.Web3Provider

ethers.utils.parseEther

```

**V6 Equivalents:**

```typescript

BrowserProvider

parseEther (direct import)

```

**Solution:** Either upgrade all hooks to v6 syntax OR pin `ethers@^5.7.0` across all workspaces.

2. Missing ABI Files

**Problem:** `useBetting.ts` imports `@/abis/BetVantaCore.json` but no `abis/` directory exists at repo root.

**Solution:**

3. Missing Contract View Function

**Problem:** `useBetting.ts` calls `getBets()` but `BetVantaCore.sol` doesn't expose this function.

**Solutions:**

4. Incorrect Solidity Import Paths

**Problem:** `contracts/core/BetVantaCore.sol` uses `./interfaces/...` imports but interfaces are in `contracts/interfaces/`.

**Solution:** Update imports to `../interfaces/...` for correct relative path resolution.

5. Root Dev Script Issues

**Problem:** Running `pnpm run dev` from repo root may fail.

**Solution:** Always run the Next.js dev server from the `frontend/` directory using the workspace filter command.

Key Reference Files

When working on similar features or debugging, consult these files:

**Forms & UI Components:**

**Web3 Patterns:**

**Contract Design:**

Instructions for AI Agents

When working in this codebase:

1. **Always verify ethers.js version** before adding Web3 code—check package.json and use consistent syntax

2. **Never modify bet state transitions** without preserving the PENDING → ACCEPTED → SETTLED flow

3. **Always ensure token approval** before requesting bets in any new UI or contract logic

4. **Use workspace-filtered pnpm commands** to avoid dependency resolution issues

5. **Check for existing hooks** before adding Web3 logic—reuse `useWeb3` and `useBetting` patterns

6. **Follow the form validation pattern** from `PlaceBetForm.tsx` for consistency

7. **Add tests** in `contracts/test/` for any contract modifications

8. **Update ABIs** after contract changes and ensure frontend imports remain valid

Safety Constraints