Installation guide

Prerequisites

Before you begin, ensure your development environment meets these requirements:

node --version
# Should be >= 20.18.3

Agora DAO requires Node.js >= 20.18.3. Using an older version may cause dependency conflicts or runtime errors.

Required software

Node.js >= 20.18.3 - Download
Yarn 3.2.3 - Installed automatically via Corepack
Git - Download
Web3 wallet - MetaMask or similar for testing

Clone the repository

Get started by cloning the Agora DAO repository:

git clone https://github.com/NightmareFox12/agora-dao-eth.git
cd agora-dao-eth

Install dependencies

Agora DAO uses Yarn 3 workspaces to manage the monorepo structure. Install all dependencies with a single command:

yarn install

This installs dependencies for both packages:

packages/hardhat - Smart contracts and Hardhat tooling
packages/nextjs - Next.js frontend application

The project uses Yarn 3 (packageManager: “[email protected]”) which is automatically managed via Corepack. You don’t need to install Yarn globally.

Project structure

Understand the monorepo layout:

agora-dao-eth/
├── packages/
│   ├── hardhat/              # Smart contracts
│   │   ├── contracts/
│   │   │   ├── AgoraDaoFactory.sol
│   │   │   ├── AgoraDao.sol
│   │   │   ├── AgoraDaoFactory/
│   │   │   │   └── Validation.sol
│   │   │   └── AgoraDao/
│   │   │       └── Rol.sol
│   │   ├── deploy/           # Deployment scripts
│   │   ├── test/             # Contract tests
│   │   ├── scripts/          # Utility scripts
│   │   └── hardhat.config.ts
│   │
│   └── nextjs/               # Frontend application
│       ├── app/              # Next.js App Router
│       ├── components/       # React components
│       ├── hooks/            # Custom hooks
│       ├── lib/              # Utilities and schemas
│       ├── public/           # Static assets
│       └── scaffold.config.ts
│
├── package.json              # Root package.json with workspace scripts
└── README.md

Smart contract setup

Configure the Hardhat environment for smart contract development.

Copy environment template

Create your environment configuration file:

cp packages/hardhat/.env.example packages/hardhat/.env

Configure environment variables

Edit packages/hardhat/.env with your API keys:

packages/hardhat/.env

# Alchemy API key for RPC access (optional for local development)
ALCHEMY_API_KEY=your_alchemy_api_key

# Etherscan API key for contract verification
ETHERSCAN_V2_API_KEY=your_etherscan_api_key

# Deployer private key (generated by yarn generate command)
DEPLOYER_PRIVATE_KEY_ENCRYPTED=

For local development, you can leave these empty. Default values are provided in hardhat.config.ts for prototyping.

Generate deployer account

Create a new deployer account or import an existing one:

yarn account:generate
# or
yarn generate

Never commit your .env file or share your private keys. The deployer account’s private key is encrypted in the .env file for security.

Compile contracts

Compile the Solidity contracts:

yarn hardhat:compile
# or
yarn compile

This generates TypeScript types and artifacts in packages/hardhat/artifacts/.

Run tests

Verify contracts work correctly:

yarn hardhat:test
# or
yarn test

Tests run with gas reporting enabled (REPORT_GAS=true).

Start local blockchain

Run a local Ethereum network for development:

yarn hardhat:chain
# or
yarn chain

This starts a Hardhat node on http://127.0.0.1:8545 with:

20 pre-funded test accounts
Instant block mining
Full Ethereum JSON-RPC support
Console logging of transactions

Leave this terminal running. Open a new terminal for subsequent commands.

Deploy contracts

Deploy the smart contracts to your local network:

Deploy to local network

In a new terminal, run:

yarn hardhat:deploy
# or
yarn deploy

This executes the deployment scripts in packages/hardhat/deploy/:

00_deploy_agora_factory.ts - Deploys AgoraDaoFactory
01_deploy_agora_dao.ts - Additional setup

Verify deployment

The deployment script will output contract addresses:

Deploying AgoraDaoFactory...
✓ AgoraDaoFactory deployed to: 0x5FbDB2315678afecb367f032d93F642f64180aa3

These addresses are automatically saved to packages/hardhat/deployments/.

Contracts are automatically deployed when you start the Next.js development server. Manual deployment is only needed if you make contract changes.

Frontend setup

Configure the Next.js application.

Copy environment template

Create your frontend environment configuration:

cp packages/nextjs/.env.example packages/nextjs/.env.local

Configure environment variables

Edit packages/nextjs/.env.local:

packages/nextjs/.env.local

# Alchemy API key for RPC access (optional)
NEXT_PUBLIC_ALCHEMY_API_KEY=your_alchemy_api_key

# WalletConnect project ID for wallet connections
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your_wallet_connect_project_id

Default values are provided in scaffold.config.ts. You only need to set these for production or if you want to use your own API keys.

scaffold.config.ts

const scaffoldConfig = {
  targetNetworks: [chains.hardhat],
  pollingInterval: 30000,
  alchemyApiKey: process.env.NEXT_PUBLIC_ALCHEMY_API_KEY || DEFAULT_ALCHEMY_API_KEY,
  walletConnectProjectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID || "3a8170812b534d0ff9d794f19a901d64",
  onlyLocalBurnerWallet: true,
};

Get API keys (optional)

For production or custom development:Alchemy API Key

Visit Alchemy Dashboard
Create a new app
Copy the API key

WalletConnect Project ID

Visit WalletConnect Cloud
Create a new project
Copy the project ID

Start development server

Launch the Next.js application:

yarn start
# or
yarn workspace @se-2/nextjs dev

The application runs on http://localhost:3000.

Connect your wallet

Open http://localhost:3000 in your browser and connect your Web3 wallet:

Click “Connect Wallet”
Select your wallet provider (MetaMask, WalletConnect, etc.)
Switch to Hardhat network (Chain ID: 31337)
Import one of the pre-funded test accounts

Make sure your wallet is connected to the Hardhat local network (Chain ID: 31337). Add it manually if needed:

Network Name: Hardhat
RPC URL: http://127.0.0.1:8545
Chain ID: 31337
Currency Symbol: ETH

Available scripts

Common commands for development:

Root level commands

# Start Next.js dev server
yarn start

# Start local blockchain
yarn chain

# Run all tests
yarn test

# Format code
yarn format

# Lint code
yarn lint

Hardhat-specific commands

cd packages/hardhat

# Compile contracts
yarn compile

# Run tests with gas reporting
yarn test

# Clean artifacts
yarn clean

# Flatten contracts
yarn flatten

Next.js-specific commands

cd packages/nextjs

# Start dev server
yarn dev

# Build production
yarn build

# Start production server
yarn serve

Network configuration

Configure different networks in packages/hardhat/hardhat.config.ts:

hardhat.config.ts

const config: HardhatUserConfig = {
  networks: {
    hardhat: {
      forking: {
        enabled: process.env.MAINNET_FORKING_ENABLED === "true",
        url: `https://eth-mainnet.alchemyapi.io/v2/${alchemyApiKey}`,
      },
    },
    sepolia: {
      url: `https://eth-sepolia.g.alchemy.com/v2/${alchemyApiKey}`,
      accounts: [deployerPrivateKey],
    },
    mainnet: {
      url: `https://eth-mainnet.g.alchemy.com/v2/${alchemyApiKey}`,
      accounts: [deployerPrivateKey],
    },
  },
};

Update scaffold.config.ts to match:

scaffold.config.ts

const scaffoldConfig = {
  targetNetworks: [chains.hardhat], // or [chains.sepolia], [chains.mainnet]
  // ...
};

Troubleshooting

Node version error

If you see “The engine ‘node’ is incompatible”:

# Check your Node version
node --version

# Install Node 20.18.3 or higher
nvm install 20.18.3
nvm use 20.18.3

Yarn not found

If Yarn 3 is not available:

# Enable Corepack
corepack enable

# Install dependencies
yarn install

Contract compilation fails

If Solidity compilation fails:

# Clean artifacts
yarn hardhat:clean

# Reinstall dependencies
rm -rf node_modules
yarn install

# Recompile
yarn compile

MetaMask connection issues

If you can’t connect to the local network:

Reset MetaMask account (Settings > Advanced > Reset Account)
Verify Hardhat network configuration:
- RPC URL: http://127.0.0.1:8545
- Chain ID: 31337
Ensure local blockchain is running (yarn chain)

Port already in use

If port 3000 or 8545 is already in use:

# Find process using port
lsof -i :3000
lsof -i :8545

# Kill process
kill -9 <PID>

# Or use different ports
PORT=3001 yarn start

Next steps

You’re all set up! Here’s what to do next:

Create your first DAO

Follow the quickstart to create and join a DAO

Explore smart contracts

Understand the contract architecture

Configure your project

Learn how to configure environment and settings

Deploy to production

Deploy your DAO to Vercel or IPFS

Get Started

Core Features

Guides

Installation guide

Prerequisites

Required software

Clone the repository

Install dependencies

Project structure

Smart contract setup

Start local blockchain

Deploy contracts

Frontend setup

Available scripts

Root level commands

Hardhat-specific commands

Next.js-specific commands

Network configuration

Troubleshooting

Next steps

Create your first DAO

Explore smart contracts

Configure your project

Deploy to production

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

​Prerequisites

​Required software

​Clone the repository

​Install dependencies

​Project structure

​Smart contract setup

​Start local blockchain

​Deploy contracts

​Frontend setup

​Available scripts

​Root level commands

​Hardhat-specific commands

​Next.js-specific commands

​Network configuration

​Troubleshooting

​Next steps

Create your first DAO

Explore smart contracts

Configure your project

Deploy to production

Build docs developers (and LLMs) love

Prerequisites

Required software

Clone the repository

Install dependencies

Project structure

Smart contract setup

Start local blockchain

Deploy contracts

Frontend setup

Available scripts

Root level commands

Hardhat-specific commands

Next.js-specific commands

Network configuration

Troubleshooting

Next steps