What it is
ChronoVault brings the two-factor authentication model people know from Google Authenticator to Web3 self-custody wallets, without giving up privacy or decentralization. A transaction sent through the wallet's proof-gated entry point requires a proof that you hold a valid TOTP (time-based one-time password) code for the current timestamp. The proof is zero-knowledge, so the secret never touches the chain.
A zero-knowledge proof (ZK proof) shows that a statement is true without revealing the data behind it.
The problem
A self-custody wallet is protected by one private key. Whoever obtains the key can move the funds. ChronoVault adds a second factor that lives on a separate device. The wallet's proof-gated entry point rejects any transaction that lacks a fresh proof from that factor.
The interesting decision was how to prove the code without leaking it. Most existing TOTP-wallet designs precompute a batch of future codes, hash them and check against a Merkle tree, a hash tree that proves membership in a set. If someone gets access to the client, they can brute-force those pre-hashed values offline. ChronoVault instead proves knowledge of the secret itself in a Circom circuit, so nothing precomputed sits on the client.
How it works
The repository is a pnpm monorepo with three packages.
| Package | Contents |
|---|---|
circuits/ | The Circom circuit src/totp_verifier.circom, plus setup and proof scripts |
blockchain/ | TOTPWallet.sol, the generated TOTPVerifier.sol, Hardhat tests, an Ignition deployment module |
frontend/ | A Next.js app with the wallet dashboard, a built-in authenticator page, and a Prisma schema |
The circuit takes four public inputs: the code, the time counter (Unix time divided by 30), the hash of the secret and a commitment to the transaction. It takes one private input, the secret. It checks that the secret matches the public hash and that the code is derived from the secret and the time counter.
A transaction then moves through two devices:
- The transaction device collects the destination, value and data. It reads the wallet nonce and computes the transaction commitment.
- The authenticator device receives that request, derives the current code and produces a Groth16 proof bound to the commitment.
- The proof returns to the transaction device. It travels either as three cycling QR codes or through a database row.
- The transaction device calls
executeWithProofon the wallet. - The wallet checks the commitment, the secret hash, the time window and the proof, then runs the call.
What I built
I built ChronoVault end to end. That covers the wallet contract, the Circom proof circuit, proof generation and verification, and the whole frontend: the landing page, the dashboard, wallet connection and the TOTP setup flow. I also added QR and polling transfer of proofs between devices, and wallet funding.
Design decisions
A ZK-friendly code instead of RFC 6238. The circuit derives the six-digit code as Poseidon(secret, timeCounter) % 1000000. Poseidon is a hash designed for ZK circuits. A comment in frontend/src/lib/totp.ts gives the reason: roughly 150 constraints, against roughly 40,000 for SHA-1 inside a circuit. The trade-off is that these codes are not standard TOTP codes. Google Authenticator cannot produce them, so the app includes its own authenticator page that stores secrets in IndexedDB.
Prove knowledge, not Merkle inclusion. The wallet stores only the Poseidon hash of the secret. The project's security notes point out that a Merkle tree of precomputed codes runs out; this design has no such list. The cost is a Groth16 trusted setup (the Powers of Tau ceremony files) and proof generation on the user's device.
Bind each proof to one transaction. The commitment is keccak256(to, value, keccak256(data), nonce) reduced modulo the BN254 field prime. It is a public input, and the contract recomputes it and compares. A relayer who sees the proof cannot redirect it to a different transaction.
Limit replay. The contract requires the time counter to be newer than the last one used and the timestamp to be within five minutes of the block time. The wallet nonce also increments. By inference from the counter check, a wallet accepts at most one proof per 30-second window.
Disable the unguarded path. execute always reverts with DirectExecuteDisabled. The comment notes this holds even if the owner's private key leaks.
Optional online transfer. The offline QR path needs no network. The online path stores the proof in a ProofTransfer table (UUID key, JSON proof) in PostgreSQL through Prisma, and the transaction device polls it. The row holds a proof bound to one transaction, not the secret.
Run it locally
Prerequisites: Node.js 22 or newer and pnpm 10. The repository includes prebuilt circuit artifacts, so the circom compiler is only needed if you change the circuit.
-
Clone the repository and install dependencies.
git clone https://github.com/WhyAsh5114/ChronoVault.git cd ChronoVault pnpm install -
In one terminal, compile the contracts and generate the TypeScript bindings.
pnpm dev:blockchain -
In a second terminal, start the frontend.
pnpm dev:frontend -
Open
http://localhost:3000.
To run the contract tests, which generate and verify real proofs, run pnpm test inside blockchain/. The online proof transfer also needs a PostgreSQL DATABASE_URL.
Reference
| Layer | Tools | Role |
|---|---|---|
| Circuit | Circom 2.2.1, circomlib, snarkjs, Groth16 | Proof system and generated Solidity verifier |
| Contracts | Solidity 0.8.28, Hardhat with viem, OpenZeppelin, ERC-4337 account-abstraction contracts | Wallet, verifier, mock entry point |
| Frontend | Next.js 15, React 19, wagmi, viem, TanStack Query | Wallet UI and chain access |
| Proof tools | circomlibjs, snarkjs, QR scanner and generator libraries | Code derivation, proofs, device transfer |
| Data | Prisma, PostgreSQL | Online proof transfer |
Outcome
- ChronoVault was built at ETHOnline 2025, an asynchronous hackathon run by ETHGlobal. The hackathon page records the result as a win, with a team of two.
- The repository description calls it an ETHOnline 2025 finalist and Hardhat track winner.
- The repository has commits from 2025-10-19 to 2025-12-08, and a live deployment.
- GitHub Actions builds the circuits, generates a test proof, tests the contracts and lints and builds the frontend.