Skip to main content
Building EduChain: Verifiable Academic Credentials with Ethereum and IPFS

Building EduChain: Verifiable Academic Credentials with Ethereum and IPFS

September 15, 2024 3 min read Web3, Blockchain, Solidity, NFT, IPFS, Ethereum, React

Building EduChain: Verifiable Academic Credentials with Ethereum and IPFS is a Developer Journal article by Ancel Ajanga on https://ancel.co.ke. Exploring the challenges and solutions in building a full-stack Web3 application that issues verifiable academic certificates as non-transferable ERC721 NFTs on Ethereum with decentralized IPFS metadata. It focuses on: Traditional paper certificates and digital PDFs are easily forged, cumbersome to verify across institutions, and vulnerable to loss or physical damage. Anc…

Exploring the challenges and solutions in building a full-stack Web3 application that issues verifiable academic certificates as non-transferable ERC721 NFTs on Ethereum with decentralized IPFS metadata.

Who this is for

Engineers, academic institutions, and product builders interested in decentralized credentials, immutable audit trails, and integrating Ethereum smart contracts into React applications.

Problem

Traditional paper certificates and digital PDFs are easily forged, cumbersome to verify across institutions, and vulnerable to loss or physical damage.

Business outcome

A decentralized credential verification platform where accredited institutions mint tamper-proof ERC721 certificates with permanent IPFS metadata, verifiable by employers in seconds.

Metrics

  • Zero-tamper cryptographic credential verification on Ethereum Sepolia
  • Decentralized IPFS metadata pinning via Pinata
  • Non-transferable ERC721 token mechanics preventing secondary credential trading

Academic credential fraud is a quiet but pervasive global problem. Traditional paper certificates and static PDF diplomas are easily forged with graphic editing software, difficult for prospective employers to verify across borders, and susceptible to loss or physical destruction. Educational institutions and employers need a transparent, decentralized method to issue and verify credentials that cannot be forged or altered.

Building EduChain was my first deep dive into Web3 engineering, bridging traditional full-stack web development with the Ethereum blockchain and decentralized storage to solve this exact problem.

The Problem: The Fragility of Academic Credentials

The traditional credentialing pipeline breaks down in three specific areas: 1. **Vulnerability to Forgery**: Anyone with basic graphic design software can produce a convincing PDF of a university diploma. Employers have no fast, automated mechanism to confirm authenticity without contacting the issuing university's registrar. 2. **Centralized Single Points of Failure**: If an institution closes or experiences a server outage, graduates are left without proof of their educational achievements. 3. **Verification Friction**: Background check agencies spend days or weeks emailing administrative offices to confirm degree conferrals.

A blockchain-based credentialing system addresses these issues by anchoring records to an immutable, decentralized ledger.

Technical Architecture: Full-Stack Web3 Integration

EduChain is architected across three coordinated layers:

### 1. Smart Contracts (Solidity & OpenZeppelin) The foundation is an **ERC721 smart contract** deployed to the Ethereum Sepolia testnet: - **Non-Transferable (Soulbound) Tokens**: By overriding the standard `_transfer` and `safeTransferFrom` functions, certificates cannot be transferred between wallet addresses. Once minted to a student's address, the token remains permanently tied to that recipient. - **Role-Based Access Control**: Only authenticated institutional addresses holding the `MINTER_ROLE` can issue new credentials, preventing unauthorized minting. - **ReentrancyGuard Protection**: Audited OpenZeppelin v5 primitives protect the contract against reentrancy vulnerabilities.

### 2. Decentralized Storage (IPFS & Pinata) Storing rich certificate media (student name, degree type, honors, graduation date, institution logo) directly on the Ethereum blockchain is cost-prohibitive due to gas fees. Instead: - Certificate metadata and rendered diplomas are pinned to the InterPlanetary File System (IPFS) via the Pinata API. - The smart contract records only the immutable **IPFS Content Identifier (CID)** as the `tokenURI`, ensuring cryptographic integrity at minimal gas cost.

### 3. Frontend & Wallet Layer (React 19, Wagmi & RainbowKit) The client interface provides a seamless experience for both institutions and students: - **RainbowKit & Wagmi**: Manages wallet connection lifecycles (MetaMask, WalletConnect, Coinbase Wallet) with automatic chain switching to Sepolia. - **Ethers.js v6**: Coordinates contract read and write transactions, handling asynchronous signers, gas estimation, and transaction confirmation listeners. - **MongoDB Read Cache**: To enable instant search, filtering, and student directory browsing without querying the blockchain for every filter change, an off-chain MongoDB instance indexes verified on-chain mint events.

Key Engineering Challenges Solved

### 1. Ethers.js v6 Asynchronous Signers Upgrading to modern ethers.js v6 introduced changes to provider and signer lifecycles. Handling browser wallet account switches or network rejections without crashing the React UI required implementing explicit state guards:

ypescript
async function mintCertificate(studentAddress: string, metadataUri: string) {
  if (!signer) throw new Error("Wallet not connected");
  
  try {
    const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, signer);
    const tx = await contract.issueCertificate(studentAddress, metadataUri);
    const receipt = await tx.wait(1); // Wait for 1 block confirmation
    return receipt.hash;
  } catch (error: any) {
    if (error.code === 'ACTION_REJECTED') {
      throw new Error("User declined transaction in wallet");
    }
    throw error;
  }
}

### 2. Multi-Environment Coordination Deploying a Web3 platform involves coordinating three separate environments: - The React frontend hosted on Netlify. - The Node.js indexing backend hosted on Render. - The Solidity smart contracts running on the Ethereum Sepolia testnet. Synchronizing contract addresses, RPC endpoints, and Pinata API keys securely required disciplined environment configuration.

Key Engineering Takeaways

1. **Hybrid Storage is Essential in Web3**: Never store large data payloads on-chain. Store verifiable cryptographic hashes and IPFS CIDs on-chain, and keep heavy data in decentralized off-chain storage. 2. **Soulbound Restrictions Protect Credential Semantics**: In educational credentials, transferability is an anti-feature. Restricting token transfers transforms an NFT from a speculative asset into a verifiable digital identity document. 3. **Clear Wallet Feedback is Critical**: Blockchain transactions involve variable gas fees and confirmation latency. Giving users explicit step-by-step UI feedback during signature and block mining stages makes Web3 feel as approachable as Web2.

Explore the EduChain Project or review the [source code on GitHub](https://github.com/Ancel-duke/EduChain).

Trade-offs

Chose non-transferable (soulbound) ERC721 NFTs over standard tokens to prevent unauthorized secondary trading; combined off-chain MongoDB indexing with on-chain Ethereum state to achieve fast browsing without paying gas fees for read queries.

Challenges faced

Handling asynchronous wallet connection states across network changes, coordinating ethers.js v6 contract signers, and managing IPFS upload timeouts gracefully.