ChainForge

Web3 RPG Forge DApp

Public application: https://chainforge-production.up.railway.app/

ChainForge is a decentralized Web3 application developed as part of the 5BLOC – Advance Your Skills in the Blockchain program.

The application allows players to mint, own, transfer, and forge weapon NFTs using a simple RPG-inspired mechanic, fully backed by on-chain logic. Weapons are implemented as ERC-721 tokens deployed on Ethereum Sepolia, with metadata and images stored on IPFS.

---

Table of Contents

• Overview
• Core Features
• Weapon Tiers System
• Technology Stack
• Prerequisites
• Local Installation
• Smart Contract Deployment
• Frontend Configuration
• Testing
• Important Notes

---

Overview

ChainForge combines blockchain fundamentals with a game-like user experience inspired by RPGs. Players can mint, own, trade, and upgrade weapon NFTs through an innovative forge mechanic, entirely managed on-chain.

Key Features

• ERC-721 NFTs on Ethereum Sepolia
• Metadata and images stored on IPFS
• 100% on-chain game logic
• Intuitive and responsive web interface
• Fully decentralized architecture (no server, no database)

---

Core Features

Wallet Connection

• Connect via MetaMask or WalletConnect
• Automatic Sepolia network detection
• Responsive UI for wrong network or disconnected wallet

Supported Providers: MetaMask, WalletConnect
Network Detection: Automatic (Sepolia)
UI Feedback: Real-time

Public Weapon Minting

• Free minting of a Bronze weapon
• One mint per wallet per cooldown period
• Cooldown enforced directly in the smart contract
• Smooth minting animation in the frontend

NFT Inventory

Fully on-chain inventory per wallet displaying:

Information	Description
Name	Unique weapon name
Tier	Rarity level (Bronze to Platinum)
Damage	Weapon power
Status	Lock status after forge
Date	Creation date
History	Transfer history

Metadata and images loaded from IPFS

Forge System

Mechanics:

1. Combine 4 weapons of the same tier
2. The 4 NFTs are burned
3. 1 higher-tier weapon is minted
4. Forge cooldown applied on-chain
5. The forged weapon is temporarily locked

Progression:

• 4 Bronze Weapons → 1 Silver Weapon
• 4 Silver Weapons → 1 Gold Weapon
• 4 Gold Weapons → 1 Platinum Weapon

Gifting System (Direct Transfer)

• Direct transfer between wallets
• No recipient validation required
• Uses ERC-721 safeTransferFrom
• Recipient sees the weapon immediately
• No backend, no escrow, no offers

On-Chain Security

• Maximum weapons per wallet enforced
• Forge cooldowns managed on-chain
• Lock system after forge
• No centralized authority after deployment

---

Weapon Tiers System

Tier	Name	Damage
0	Bronze	10
1	Silver	25
2	Gold	50
3	Platinum	100

---

Technology Stack

Blockchain

• Smart Contracts: Solidity ^0.8.0
• Framework: Hardhat
• Libraries: OpenZeppelin Contracts
• Network: Ethereum Sepolia Testnet

Frontend

• Framework: Next.js (App Router)
• UI Library: React 18+
• Styling: TailwindCSS
• Web3 Tools: wagmi, RainbowKit, viem
• Animations: Framer Motion

Storage

• Protocol: IPFS
• Service: Pinata

---

Prerequisites

Node.js and npm

Required:

• Node.js version 18 or higher
• npm version 9 or higher

Check installed versions:

node -v
npm -v

MetaMask Wallet (Required)

A MetaMask account is required to use the application.

Setup steps:

1. Install the MetaMask browser extension
2. Create or import a wallet
3. Enable test networks
4. Switch to the Sepolia network

Installation link:
https://chromewebstore.google.com/detail/metamask/nkbihfbeogaeaoehlefnkodbefgpgknn

SepoliaETH (Test ETH)

You need SepoliaETH to:

• Deploy the smart contract
• Mint, forge, and transfer weapons

Available Faucets:

Service	Type	Link
Mining Faucet	PoW	https://sepolia-faucet.pk910.de/
Google Cloud	Direct	https://cloud.google.com/application/web3/faucet/ethereum/sepolia

---

Local Installation

Step 1: Clone the repository

git clone https://github.com/MathisDulieu/ChainForge.git
cd chainforge-project

Step 2: Install dependencies

# Root dependencies
npm install

# Frontend dependencies
cd frontend
npm install

---

Smart Contract Deployment

Environment Variables Configuration

Create a .env file at the project root:

SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY
PRIVATE_KEY=0xYOUR_PRIVATE_KEY

Getting an Infura Key

1. Go to https://app.infura.io
2. Create an account
3. Create a new Ethereum project
4. Copy the Project ID
5. Insert it into the RPC URL

Getting Your Private Key

From MetaMask:

1. Open MetaMask
2. Click on the account menu
3. Open account details
4. Export private key
5. Paste it into the .env file

IMPORTANT: NEVER share your private key!

Compilation and Deployment

# Compile smart contracts
npx hardhat compile

# Deploy to Sepolia
npx hardhat run scripts/deploy.js --network sepolia

Note: Save the deployed contract address!

---

Frontend Configuration

IPFS Metadata Deployment

Before configuring the frontend, you need to deploy the metadata and images to IPFS using Pinata.

Project structure:

ipfs/
├── images/
│   ├── bronze.png
│   ├── silver.png
│   ├── gold.png
│   └── platinum.png
└── metadata/
    ├── bronze.json
    ├── silver.json
    ├── gold.json
    └── platinum.json

Step 1: Deploy images to Pinata

1. Go to https://app.pinata.cloud/ipfs/files
2. Upload the 4 images from the ipfs/images/ folder
3. Copy the CID (Content Identifier) for each image

Step 2: Update JSON files with image CIDs

For each JSON file in ipfs/metadata/, update the "image" field with the corresponding CID:

{
  "name": "Bronze Weapon",
  "description": "A basic bronze weapon",
  "image": "ipfs://YOUR_IMAGE_CID_HERE",
  ...
}

Example:

"image": "ipfs://bafkreidfvoldosbeajtqevthi5mrryf6b6lta2tazu255ez5dsleiooomy"

Step 3: Deploy metadata JSON files to Pinata

1. Upload the 4 updated JSON files from the ipfs/metadata/ folder to Pinata
2. Copy the CID for each JSON file

Environment Variables Configuration

Create a frontend/.env.local file:

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID
NEXT_PUBLIC_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY
NEXT_PUBLIC_CHAIN_ID=11155111
NEXT_PUBLIC_IPFS_GATEWAY=https://gateway.pinata.cloud/ipfs/
NEXT_PUBLIC_CONTRACT_ADDRESS=DEPLOYED_CONTRACT_ADDRESS

NEXT_PUBLIC_TIER0_URI=ipfs://YOUR_BRONZE_JSON_CID
NEXT_PUBLIC_TIER1_URI=ipfs://YOUR_SILVER_JSON_CID
NEXT_PUBLIC_TIER2_URI=ipfs://YOUR_GOLD_JSON_CID
NEXT_PUBLIC_TIER3_URI=ipfs://YOUR_PLATINUM_JSON_CID

NEXT_PUBLIC_DEPLOY_BLOCK=YOUR_DEPLOY_BLOCK_NUMBER

Getting a WalletConnect Project ID

1. Go to https://cloud.walletconnect.com
2. Create a project
3. Copy the Project ID

Getting the Deploy Block Number

The deploy block is the block number where your smart contract was deployed on Sepolia.

1. Go to https://sepolia.etherscan.io/
2. Search for your deployed contract address
3. On the contract page, look for the "Contract Creation" transaction
4. Click on the transaction hash
5. The block number is displayed on the transaction details page
6. Copy this block number and paste it as NEXT_PUBLIC_DEPLOY_BLOCK

Example: If your contract was deployed at block 10104574, set:

NEXT_PUBLIC_DEPLOY_BLOCK=10104574

Launch the Frontend

cd frontend
npm run dev

Open http://localhost:3000 in your browser.

---

Testing

Run the smart contract test suite:

npx hardhat test

Tests covered:

• Weapon minting
• Forge system
• NFT transfers
• Cooldown management
• Wallet limits

---

Important Notes

Architecture

• No backend used
• No database
• Full decentralization

Security

• 100% on-chain logic
• Frontend = blockchain mirror
• Immutable after deployment

Deployment

• Hosted on Railway
• Production mode
• Available 24/7

Key Points

• All game logic is executed on-chain
• The frontend only reflects the blockchain state
• No centralized server is required
• NFTs and metadata are stored in a decentralized manner
• The public deployment is accessible to everyone

---

Developed as part of the 5BLOC – Advance Your Skills in the Blockchain program