Credentia: The Zero-Knowledge Handshake for Digital Credentials

How a hybrid of Sepolia events and IPFS CIDs creates a verifiable, time-bound audit trail for sensitive documents without the gas-heavy overhead of on-chain storage.

7 min read • View on GitHub • More from elango-t

A giant magnifying glass hovering over a wax seal, revealing complex gears inside — The Commit-Reveal mechanism hides complex verification logic behind a simple cryptographic seal.

Key Takeaways

Credentia uses a commit-reveal architecture to verify document integrity without exposing sensitive data on a public ledger.
The system splits workloads across MongoDB for fast searching, IPFS for file storage, and Sepolia smart contracts for access control.
Smart contracts enforce time-bound permissions by comparing the blockchain's internal clock against specified expiration windows.
The application treats the local database as a cache and reconstructs the audit trail by replaying event logs directly from the blockchain.

The Integrity Paradox

Digital certificates are fundamentally broken. A PDF is trivial to forge, and a centralized database is a single point of failure. Employers need to know a document has not been altered, but universities cannot afford to expose student data on a public ledger. This creates a trust gap.

Credentia solves this with a commit-reveal architecture. It relies on client-side hashing where the browser proves the file's identity before the server ever sees it. The blockchain does not store the certificate itself. It stores a cryptographic promise.

A four-node interaction flow showing the Verification Handshake. Node 1 is University (Issuer). Node 2 is Student (Holder). Node 3 is Employer (Verifier). Node 4 is Blockchain (Registry). Show a file being hashed at the University

The Three-Layer Cake

Building a decentralized application entirely on-chain is too expensive and too slow. Credentia splits the workload across three distinct layers to optimize for speed, persistence, and truth.

The searchable shell lives in MongoDB via Next.js. This allows fast queries for student names and graduation years. The immutable box is IPFS, holding the actual PDF files. The master key is a Solidity smart contract on Sepolia, which dictates exactly who can read the IPFS hash and for how long.

A layered architecture stack. Top layer is the UI Table mapping to MongoDB (highlighting Student Name). Middle layer is IPFS (highlighting PDF File). Bottom layer is the Sepolia Blockchain (highlighting Access Hash and Expiry). Show vertical lines connecting a single "certId" across all three layers.

Consent with an Expiration Date

The most critical feature of any credential system is revocation. Once you share your academic record, you should be able to un-share it. Credentia handles this natively in the smart contract using time-bound permissions.

Instead of relying on a centralized server cron job to revoke access, the `ChainConsent.sol` contract uses the blockchain's own clock. When granting access, the issuer specifies a duration. The contract simply checks if `block.timestamp` has passed the expiration window.

function hasAccess(uint256 fileId, address user) public view returns (bool) {
    if (fileOwner[fileId] == user) return true;
    return block.timestamp < accessExpiry[fileId][user];
}

Reconstructing Truth from the Fog

Most applications trust their local database implicitly. Credentia treats its database as a cache and treats the blockchain as the ultimate source of truth. This is achieved through event sourcing.

The frontend hook `useAccessLogs.ts` queries the Sepolia testnet for specific events like `AccessGranted` and `CertificateVerified`. By replaying these logs, the application reconstructs the entire history of a document. It builds a verifiable audit trail without relying on a centralized logging server.

A lighthouse emitting a stream of binary code to illuminate ghostly ships in the dark water — Event sourcing acts as a lighthouse, scanning the blockchain's history to reconstruct the truth of past transactions.

The Verification Spectrum

Decentralized identity requires balancing cost, privacy, and security. Pure on-chain solutions fail on privacy and cost. Centralized databases fail on tamper-resistance. Credentia finds the middle ground.

Architecture	Data Storage	Tamper-Resistance	Access Control
Centralized DB	AWS / Postgres	Low (Admin can edit)	Opaque internal logic
Pure On-Chain	Ethereum State	Maximum	Permanent and public
Credentia Hybrid	IPFS + MongoDB	High (Cryptographic hashes)	Time-bound smart contracts

Sources: Codebase analysis of elango-t/Credentia.