What Changed In V2

BERT Protocol V2 is not a full reset of the stack. It is a targeted upgrade of the modules that shape execution quality after a vote. The main contract updates are IdeaRegistry, FundingPool, and GrantManager.

For integrators, the practical consequence is simple: round creation and voting stay conceptually familiar, but the post-settlement path is now richer. Indexers, frontend pages, and operational runbooks should account for review events, low-quality markers, staged payouts, milestone proof requests, and reviewer validation outcomes.

Quick Start (5 min)

This is the shortest reliable flow to run BERT locally and submit real transactions from the UI. Use one terminal for Hardhat node and another for frontend.

# Terminal A
npx hardhat node

# Terminal B (core/deploy)
npx hardhat run scripts/deploy/deploy-proxies.ts --network localhost
npx hardhat console --network localhost

# Terminal C (frontend)
npm run dev

Then copy deployed proxy addresses into .env and keep NEXT_PUBLIC_HARDHAT_RPC_URL=http://127.0.0.1:8545 if frontend runs on the same machine/browser profile.

Architecture Entry Points

Start from contract boundaries, not UI screens. For proposal data read IdeaRegistry; for rounds and vote constraints read VotingSystem; for balances and stake accounting read FundingPool; for payout execution read GrantManager; for permissions read RolesRegistry.

Frontend integration root is src/lib/contracts.ts (ABI + addresses) and src/lib/web3.ts (wagmi config). If a view breaks, first verify these two files and environment variables.

Treat events as the source for history screens and view calls as source for live state. This avoids stale UI when users refresh during active voting windows.

Local Setup

Recommended startup order: run local node, deploy proxies, mint local MockUSDC if needed, copy deployed addresses into frontend env, then run frontend. Keep one deployment session per test cycle; restarting node invalidates old addresses.

Most common integration bug is network mismatch: wallet on one RPC, frontend on another. Confirm chain ID and RPC host alignment before debugging contract logic.

Contract Integration

Core write flows are: createIdea, startVotingRound, vote, endVotingRound, grant execution path, and author completion marker. Always surface readable pre-check errors in UI before opening wallet prompt.

For token-based actions, sequence matters: ensure user balance, then approval, then protocol write call. Failed approvals or stale allowance are frequent root causes.

The Graph Integration

BERT frontend supports hybrid reads: direct on-chain RPC plus indexed reads from The Graph. In V2, indexed coverage matters more because the protocol now emits a broader execution trail than simple ideas and votes. Set NEXT_PUBLIC_SUBGRAPH_URL to enable indexed queries for rounds, ideas, reviews, milestone activity, and payout-related history.

Production recommendation: keep subgraph start blocks aligned with original proxy deployment blocks when using upgradeable contracts, monitor indexing status in Studio, and keep RPC fallback enabled for critical live reads.

Wallet & RPC Alignment

Most transaction issues are not Solidity bugs. They are RPC mismatches between wallet, frontend transport, and node host. Keep all three on the same chain ID (31337 for local Hardhat) and same reachable RPC endpoint.

State & Status Model

Idea lifecycle is policy-critical: Pending -> Voting -> WonVoting/Rejected -> Funded -> Completed. If a write action fails, verify status first. Many operations are deliberately stage-restricted.

Review/curation permissions are also status-bound and role-bound. Keep client-side validation aligned with contract guards to avoid confusing raw revert output.

V2 adds another layer that frontend and indexer developers should model explicitly: grant execution has internal checkpoints even when high-level idea status still looks familiar. Initial claim, milestone review state, and later releases should be treated as first-class UI concepts rather than hidden side effects.

Error Handling UX

Never show raw wallet/viem payloads as final user message. Decode and map known errors into actionable UI text. Example: instead of Internal error, show “Action available only in Voting status.”

Keep two layers: pre-flight validation (client-side checks before signature) and post-tx parsing (friendly fallback if chain call still reverts).

Admin & Safety

Admin setters are powerful and must be treated as governance-level changes. Parameter updates can alter fairness, treasury behavior, and user eligibility.

Incident policy is explicit: pause -> diagnose -> patch -> verify -> unpause. Never resume writes before post-fix verification of roles and parameters.

Testing Workflow

Minimum pre-merge checks: contract tests pass, critical UI writes tested end-to-end (idea creation, voting, payout path), and regression of role/status guards.

For frontend stability, verify hydration-sensitive pages and wallet-connected pages in a clean browser profile to reduce extension noise during debugging.

Release Checklist

Production Readiness

Before Arc/public rollout: verify addresses, verify role wiring, verify pause state, verify key parameters, and run smoke transactions from a non-admin user.

Keep deployment manifests, tx hashes, and policy snapshots versioned. This makes incidents diagnosable and changes auditable.

For each release, keep a short changelog entry with: changed contracts, changed UI flows, migration steps, rollback plan, and operator owner.