🏙️ BlockCity Hub — Web3 dApp

Welcome to BlockCity Hub 🚀
This is a complete Web3 dApp built during the BlockCity Workshop.

It connects to 4 Smart Contracts deployed on Sepolia Testnet:

1. City Foundation (Base Contract)
2. Treasury (ERC-20 Token)
3. Identity (NFT Badges)
4. Council (On-chain Voting / DAO)

---

Project Structure

BLOCKCITY/
│
├── index.html
│
├── assets/
│   ├── css/
│   │   └── styles.css
│   │
│   └── js/
│       ├── app.js 
        |---canvas.js
│       │
│       ├── config/
│       │   └── contracts.js
│       │
│       ├── core/
│       │   ├── connect.js
│       │   ├── helpers.js
│       │   ├── loader.js
│       │   └── state.js
│       │
│       └── rooms/
│           ├── room1.foundation.js
│           ├── room2.treasury.js
│           ├── room3.identity.js
│           └── room4.council.js

---

🛠 Requirements (Beginner Setup Guide)

1️⃣ Install VS Code

Download: https://code.visualstudio.com/

---

2️⃣ Install Live Server Extension

In VS Code:

• Go to Extensions
• Search for Live Server
• Install it

---

3️⃣ Install MetaMask

Download: https://metamask.io/

• Create a wallet
• Save your Secret Recovery Phrase safely

---

4️⃣ Add Sepolia Testnet

In MetaMask:

• Click Network dropdown
• Enable "Show test networks"
• Select Sepolia

---

5️⃣ Get Free Sepolia ETH (For Gas Fees)

Use a faucet:

https://sepoliafaucet.com/

Paste your wallet address and request ETH.

You need Sepolia ETH to:

• Mint tokens
• Create proposals
• Vote
• Mint NFTs

---

How To Run The Project

Step 1

Open the BLOCKCITY folder in VS Code.

Step 2

Right-click index.html.

Step 3

Click "Open with Live Server"

Do NOT open with file://
Modules require a local server.

How The Architecture Works

This project uses modular structure:

🔹 config/

Contains contract addresses and ABIs.

🔹 core/

Contains:

• Wallet connection
• Global state
• Shared helper functions
• Data loader

🔹 rooms/

Each smart contract has its own JS file.

Room files contain:

• Read functions
• Write functions
• UI interaction logic

app.js

Main entry file that connects everything together.

---

Smart Contracts Overview

Room 1 — City Foundation

• View platform name
• Update city name

Room 2 — Treasury (ERC-20)

• Mint tokens
• Reward users
• View balance

Room 3 — Identity (NFT)

• Mint badge NFT
• Lookup owner
• View metadata URI

Room 4 — Council (DAO)

• Create proposal
• Vote YES / NO
• Check results
• Execute proposal

---

Common Errors & Fixes

Page is blank

Make sure:

• You are using Live Server
• styles.css exists in assets/css/
• No red errors in DevTools console (F12)

---

MetaMask not found

Make sure:

• MetaMask extension installed
• Using Chrome or Brave
• MetaMask unlocked

---

Not enough gas

Get more Sepolia ETH from faucet.

---

Contract not found

Make sure:

• You pasted correct contract addresses
• Contracts are deployed on Sepolia
• MetaMask is connected to Sepolia

---

How To Add New Functionality

1. Add a new function in Solidity (Remix)
2. Recompile
3. Copy updated ABI
4. Paste ABI into contracts.js
5. Add new function in corresponding room file
6. Add button in HTML

No other changes required.

Technologies Used

• HTML
• CSS
• JavaScript (ES Modules)
• Ethers.js v6
• MetaMask
• Sepolia Testnet

No frameworks. No backend. Fully client-side Web3 dApp.

---

Learning Goals

By completing this project, you understand:

• How frontend connects to smart contracts
• How to use Ethers.js
• How to structure Web3 projects
• How to deploy dApps
• How DAOs work
• How NFTs work
• How ERC-20 tokens work

---

Final Note

This is not just a workshop demo.

This is real Web3 architecture.

You can expand this into:

• A marketplace
• A DAO governance system
• A token economy
• A student certificate system
• A voting app
• A startup MVP

Build boldly 🚀

---

# ✅ What This README Covers

✔ Folder structure
✔ Beginner setup
✔ MetaMask setup
✔ Sepolia faucet
✔ Live Server instructions
✔ Common errors
✔ Deployment
✔ Architecture explanation
✔ Expansion guide