Certificate in Web3 — Blockchain-Verified Certificate Management System
This is a closed-source, industry-level project. This post is a technical case study covering the architecture, design decisions, and engineering challenges — not a code walkthrough.
The Problem
Certificate fraud is a real and growing issue. Traditional systems rely entirely on a central authority to confirm authenticity — which means they can be compromised, go offline, or simply be trusted incorrectly. There's no independent verification path.
The client needed a system where every issued certificate could be verified by anyone, at any time, without contacting the issuer. Immutability and auditability were non-negotiable requirements.
The Solution
Each certificate's SHA-256 hash is written to the Polygon blockchain at the moment of issuance. Verification becomes a simple on-chain lookup — no issuer involvement, no central database to trust. The hash either exists on-chain or it doesn't.
The backend is built on FastAPI, with a fully automated pipeline that handles PDF generation, on-chain storage, cloud upload, and email delivery in a single workflow run.
Architecture
The system is organized into four distinct layers:
API layer handles all external interactions — authentication, certificate verification, configuration management, and hash permission controls.
Core pipeline is an orchestrated workflow engine. A runner kicks off a sequence of discrete steps, each responsible for one stage of the issuance process. Steps are isolated so a failure in one record doesn't abort the entire batch.
Service layer contains the actual integrations — PDF generation from templates, SHA-256 hashing, Polygon smart contract writes, Storj decentralized storage uploads, and SMTP email delivery.
Data layer is MariaDB for record management, with a separate blockchain monitor service that watches on-chain events and syncs state back to the database.
Authentication Design
Rather than passwords or API keys, the system uses Ethereum wallet signatures for authentication. Users sign a server-issued nonce with their private key, and the server recovers the signer address to verify identity. A JWT is issued on success.
This was a deliberate choice — the client's team already operated with Ethereum wallets, and wallet-based auth eliminates a whole class of credential management problems. No passwords to store, no reset flows to build.
Access is role-based with a clear hierarchy: contract signers have the highest privilege, followed by approvers, connected wallets, and public access. Each endpoint enforces a minimum required role.
Certificate Issuance Pipeline
The pipeline runs in ordered steps:
- Fetch pending records from the database
- Render PDFs from DOCX templates
- Compute SHA-256 hash of each PDF
- Write hashes to the Polygon smart contract
- Upload PDFs to Storj
- Send notification emails with download links
Polygon was chosen over Ethereum mainnet specifically for gas costs. Storing thousands of hashes on mainnet would be economically impractical. Polygon gives the same immutability guarantees at a fraction of the cost.
Security: Reveal Tokens
Configuration management was a tricky area. Admins need to update live credentials — database connections, RPC endpoints, storage keys — without restarting the server. But exposing those values through an API is a risk.
The solution is a reveal token system. Sensitive config values are masked by default in all API responses. To see an unmasked value, an admin requests a short-lived reveal token tied to a specific config section. Tokens are single-use with a 30-second TTL, and every reveal is logged with IP address and user-agent for audit purposes.
This keeps the convenience of a live config API without leaving sensitive data exposed in responses.
Certificate Revocation
Certificates can be revoked without deleting records. The hash permissions system lets authorized signers mark a hash as revoked on-chain. The public verification endpoint reflects this — a revoked certificate returns a clear revoked status even though the underlying record is preserved. This matters for cases like credential fraud or certificates that have a defined expiry.
Deployment
The system runs in Docker with separate containers for the API, database, and the blockchain monitor. Configuration updates trigger automatic service restarts for affected components, so there's no manual intervention needed when credentials rotate.
Reflections
The most interesting design challenge was the reveal token system — balancing operational convenience against security. A live config API is genuinely useful for an ops team, but the naive implementation is a liability. The single-use, short-TTL token approach threads that needle well.
The wallet authentication model also turned out to be a good fit beyond just the technical reasons. It aligns naturally with how the client's team thinks about identity and access, which made adoption straightforward.
This project is closed source. Architecture diagrams are shared with permission.