Local Setup

Get SHIELD running locally for development and testing.

Prerequisites

Node.js 18+ (recommend using nvm)
npm 9+ or pnpm
Git
PostgreSQL 14+ (local or cloud)
MetaMask or other wallet with test ETH

Quick Start

1. Clone the Repository

git clone https://github.com/Babs0022/SHIELD.git
cd SHIELD

2. Install Dependencies

Root dependencies:

npm install

Frontend dependencies:

cd frontend
npm install
cd ..

Contract dependencies:

cd contracts
npm install
cd ..

3. Set Up Environment

Create .env.local in the frontend directory:

cd frontend
cp .env.example .env.local

Edit .env.local:

# Required
DATABASE_URL="postgresql://user:password@localhost:5432/shield"
PINATA_JWT="your_pinata_jwt_here"
PINATA_GATEWAY_URL="https://gateway.pinata.cloud"
NEXT_PUBLIC_SHIELD_CONTRACT_BASE_SEPOLIA="0x..."
ALCHEMY_API_KEY="your_alchemy_key"
NEXT_PUBLIC_WC_PROJECT_ID="your_walletconnect_project_id"
SESSION_SECRET="generate_a_random_32_char_string"

# Optional
NEXT_PUBLIC_APP_URL="http://localhost:3000"

4. Set Up Database

Create PostgreSQL database:

createdb shield

Run migrations:

cd frontend
npm run db:setup

Or manually create tables (see Database Schema docs).

5. Get Test ETH

For Base Sepolia:

Go to Base Sepolia Faucet
Connect your wallet
Request test ETH

6. Deploy Contracts (Optional)

For local contract testing:

cd contracts
npx hardhat node

In another terminal:

cd contracts
npx hardhat run scripts/deploy.ts --network localhost

Copy the deployed contract address to your .env.local.

7. Start Development Server

cd frontend
npm run dev

Open http://localhost:3000.

Project Structure

SHIELD/
├── contracts/          # Hardhat project
│   ├── contracts/      # Solidity contracts
│   ├── test/          # Contract tests
│   └── scripts/       # Deployment scripts
│
├── frontend/          # Next.js application
│   ├── src/
│   │   ├── app/       # App router
│   │   ├── components/# React components
│   │   ├── lib/       # Utilities
│   │   └── ...
│   └── public/        # Static assets
│
└── docs/             # Documentation (this!)

Development Workflow

Frontend Development

cd frontend

# Start dev server with hot reload
npm run dev

# Run linting
npm run lint

# Type check
npx tsc --noEmit

# Build for production
npm run build

Contract Development

cd contracts

# Compile contracts
npx hardhat compile

# Run tests
npx hardhat test

# Deploy to Sepolia
npx hardhat run scripts/deploy.ts --network baseSepolia

# Verify on BaseScan
npx hardhat verify --network baseSepolia DEPLOYED_ADDRESS

Testing

Run all tests:

# Frontend tests
cd frontend
npm test

# Contract tests
cd contracts
npx hardhat test

Common Issues

MetaMask not connecting

Ensure you’re on the right network (Base Sepolia for testing)
Reset MetaMask: Settings → Advanced → Reset Account
Check console for errors

Database connection errors

Verify PostgreSQL is running
Check DATABASE_URL format
Ensure database exists: createdb shield

Contract calls failing

Verify contract address in .env
Ensure you have test ETH
Check you’re on the right network

IPFS upload failing

Verify PINATA_JWT is set
Check JWT hasn’t expired
Ensure file size under limit

Build errors

Clear .next cache: rm -rf .next
Reinstall dependencies: rm -rf node_modules && npm install
Check Node version: node --version

IDE Setup

VS Code Extensions

Recommended extensions:

ESLint - JavaScript/TypeScript linting
Prettier - Code formatting
Solidity - Solidity syntax highlighting
Tailwind CSS IntelliSense - CSS autocomplete

Settings

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.workingDirectories": ["./frontend", "./contracts"]
}

Next Steps

Read about Environment Variables
Learn the API Reference
Deploy to Vercel

Getting Started

API Reference

Smart Contracts

Local Setup

Local Setup

Prerequisites

Quick Start

1. Clone the Repository

2. Install Dependencies

3. Set Up Environment

4. Set Up Database

5. Get Test ETH

6. Deploy Contracts (Optional)

7. Start Development Server

Project Structure

Development Workflow

Frontend Development

Contract Development

Testing

Common Issues

IDE Setup

VS Code Extensions

Settings

Next Steps

​Local Setup

​Prerequisites

​Quick Start

​1. Clone the Repository

​2. Install Dependencies

​3. Set Up Environment

​4. Set Up Database

​5. Get Test ETH

​6. Deploy Contracts (Optional)

​7. Start Development Server

​Project Structure

​Development Workflow

​Frontend Development

​Contract Development

​Testing

​Common Issues

​IDE Setup

​VS Code Extensions

​Settings

​Next Steps

Local Setup

Prerequisites

Quick Start

1. Clone the Repository

2. Install Dependencies

3. Set Up Environment

4. Set Up Database

5. Get Test ETH

6. Deploy Contracts (Optional)

7. Start Development Server

Project Structure

Development Workflow

Frontend Development

Contract Development

Testing

Common Issues

IDE Setup

VS Code Extensions

Settings

Next Steps