Skip to main content

​
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:
  1. Go to Base Sepolia Faucet
  2. Connect your wallet
  3. 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

  • Ensure you’re on the right network (Base Sepolia for testing)
  • Reset MetaMask: Settings → Advanced → Reset Account
  • Check console for errors
  • Verify PostgreSQL is running
  • Check DATABASE_URL format
  • Ensure database exists: createdb shield
  • Verify contract address in .env
  • Ensure you have test ETH
  • Check you’re on the right network
  • Verify PINATA_JWT is set
  • Check JWT hasn’t expired
  • Ensure file size under limit
  • 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