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 run scripts/deploy/deploy-faucet.ts --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, deploy faucet, 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. Set NEXT_PUBLIC_SUBGRAPH_URL to enable indexed queries for rounds, ideas, and votes pages.

Production recommendation: keep subgraph start blocks close to deployment blocks, monitor indexing status in Studio, and keep RPC fallback enabled for critical 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.

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 Sepolia/public rollout: verify addresses, verify role wiring, verify pause state, verify key parameters, and run smoke transactions from 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.