WrapHub

The clean product layer for Zama ERC-20 to ERC-7984 wrapper pairs.

WrapHub turns the official Zama Wrappers Registry into a usable workspace: browse canonical pairs, claim Sepolia test tokens, wrap and unwrap, decrypt your own confidential balances, inspect onchain activity, deploy new wrappers, and route custom pairs through maintainer review — all from one polished interface.

Most teams do not need another fragmented wrapper deployment. They need one place to discover pairs, run the full confidential token lifecycle, and graduate from local testing to indexed registry coverage without rewriting the product every time a new token appears.

At A Glance

• Official-first registry: reads the Zama Wrappers Registry on Sepolia and separates official pairs from custom coverage.
• Full token lifecycle: wrap, unwrap, and wallet-scoped decrypt in a single pair workspace.
• Gasless Sepolia faucet: claim official mock ERC-20 tokens before wrapping them into confidential form.
• Create wrapper flow: deploy a confidential wrapper through WrapHub's factory, then optionally request registry listing.
• Maintainer console: review submissions, deploy missing wrappers, and list pairs for subgraph indexing.
• Indexed activity: Goldsky subgraphs power token metrics and activity tables on Sepolia and local Hardhat.
• Production-shaped UX: localized routes, wallet reconnect, friendly errors, maintainer gates, and mobile-friendly layouts.
• Developer-ready monorepo: Next.js frontend, Hardhat contracts, Supabase submission queue, subgraph manifests, and Hardhat tests.

What WrapHub Is

WrapHub is a registry and operations workspace for confidential ERC-7984 wrapper pairs.

It is built for:

• developers integrating Zama confidential tokens without rebuilding registry UX from scratch
• teams testing wrap, unwrap, and decrypt flows on Sepolia or local Hardhat
• maintainers curating custom pair submissions and enabling subgraph coverage
• end users who need a clear path from public ERC-20 balance to encrypted balance and back

The product is organized around a few durable surfaces:

• Registry: search official and custom pairs, preview metadata, and open pair workspaces.
• Pair workspace: wrap, unwrap, decrypt, inspect passport data, and read indexed activity.
• Faucet: claim eligible Sepolia mock tokens with a gasless relayer flow.
• Decrypt: reveal your own balance for any pasted ERC-7984 token address.
• Create wrapper: deploy a confidential wrapper for a public ERC-20 and optionally queue it for maintainer review.
• Maintainer console: approve, deploy, list, or reject pair submissions.

Why It Matters

Confidential wrappers are powerful, but the surrounding product work is easy to underestimate.

Without a focused registry layer, teams usually end up with:

• scattered wrapper addresses and inconsistent metadata
• no shared place to wrap, unwrap, and decrypt
• custom pairs trapped in local browser storage
• activity tables rebuilt from RPC log scans
• no clear handoff from "we deployed a wrapper" to "this pair is indexed and usable"

WrapHub turns that into a product workflow:

1. browse official pairs from the Zama registry
2. claim test tokens from the faucet when needed
3. wrap public balances into confidential form
4. decrypt only the connected wallet's balance
5. unwrap back to the public token when required
6. deploy new wrappers through the factory when no pair exists yet
7. submit custom pairs or registration requests for maintainer review
8. list approved pairs onchain so the subgraph starts indexing activity

Core Capabilities

Official Registry Workspace

WrapHub reads the Zama Wrappers Registry on Sepolia and enriches live pairs with stable display metadata.

Best for:

• discovering canonical Zama pairs
• inspecting wrapper and underlying addresses
• opening the pair workspace for wrap, unwrap, and decrypt actions

How it works:

• onchain registry reads provide the source of truth for official pairs
• seed metadata in frontend/src/features/registry/config/official-pairs.ts improves labels and defaults
• the Registry page separates Official and Custom coverage

Wrap, Unwrap, And Decrypt

Each pair workspace exposes the full confidential token lifecycle.

Best for:

• moving from public ERC-20 balances into ERC-7984 balances
• returning confidential balances to public form
• revealing the connected wallet's encrypted balance through EIP-712 user decryption

How it works:

• wrap reads ERC-20 balance and allowance, handles approval when needed, then submits the shield transaction
• unwrap encrypts the requested amount, submits the confidential unwrap flow, and finalizes the public side when required
• decrypt uses the Zama relayer and wallet authorization to reveal only the connected wallet's own balance

Sepolia Faucet

WrapHub includes a gasless faucet for official Sepolia mock tokens.

Best for:

• getting test ERC-20 balances before wrapping
• demoing the full public-to-confidential flow without funding users with Sepolia ETH for every claim

How it works:

• the frontend calls a server-side relayer route
• the relayer submits the claim through WrapHubFaucet
• the faucet contract enforces token eligibility and cooldown rules

Create Wrapper

Users can deploy a confidential wrapper for any public ERC-20 through WrapHub's factory.

Best for:

• tokens that do not yet have a factory wrapper
• teams that need the wrapper address immediately while registry listing happens later

How it works:

• WrapHub reads ERC-20 metadata and deploys through ConfidentialTokenFactory
• the factory emits WrapperDeployed on deploy
• users can keep the wrapper for themselves or request WrapHub registration
• registration requests are stored in Supabase for maintainer review

Custom Pairs And Maintainer Listing

WrapHub supports custom pair intake without pretending local config is official registry coverage.

Best for:

• adding known ERC-20 and wrapper addresses from the Registry UI
• routing new pairs through maintainer review on Sepolia or local Hardhat

How it works:

• users submit pair details from the Registry page or Create wrapper flow
• maintainers review the queue at /registry/maintainer
• List calls recordPairForIndexing and emits TokenWrapped
• the subgraph factory datasource creates a dynamic wrapper template and begins indexing activity

Important design rule:

• user deploy and maintainer deploy emit WrapperDeployed
• subgraph indexing begins only after maintainer List, which emits TokenWrapped

Indexed Activity And Metrics

Token pages read live balances from RPC, but activity and summary metrics come from subgraphs.

Best for:

• wrapper activity tables
• wrap, unwrap, transfer, and faucet claim counts
• token-page metrics without scanning logs in the browser

How it works:

• official Sepolia wrappers are indexed statically in subgraph/subgraph.yaml
• factory-listed custom pairs are indexed dynamically through a FactoryWrapper template
• the frontend selects the correct subgraph endpoint by chain ID

Privacy Model

WrapHub is explicit about what stays public and what stays private.

Public

• pair metadata and contract addresses
• registry source and network labels
• transaction hashes and explorer links
• indexed public amounts such as wrap inputs and finalized unwrap outputs
• faucet claim events and cooldown timestamps

Private

• confidential ERC-7984 balances before user decryption
• encrypted handles stored by the subgraph
• decrypted values after a wallet authorizes reveal

Wallet-Scoped Decrypt

WrapHub never presents a global decrypted balance table. Decrypt actions require wallet authorization and reveal only the connected wallet's own confidential balance.

Product Surfaces

All routes are localized through next-intl under /en, /fr, /vi, and /ko.

Route	Purpose
/	Product overview and registry preview
/registry	Official and custom pair discovery
/registry/[pairId]	Pair workspace: wrap, unwrap, decrypt, metrics, activity
/registry/create	Deploy a confidential wrapper
/registry/maintainer	Maintainer review queue and listing actions
/faucet	Sepolia gasless mock token claims
/decrypt	Decrypt any ERC-7984 token by address

How The Main Flows Fit Together

Registry
  |
  |-- Official tab -> Zama onchain registry pairs
  |-- Custom tab -> browser pairs + listed submissions
  |
Pair workspace
  |
  |-- Wrap public ERC-20 -> confidential balance
  |-- Unwrap confidential balance -> public ERC-20
  |-- Decrypt connected wallet balance
  |-- Read subgraph activity + metrics
  |
Create wrapper
  |
  |-- Deploy wrapper through factory (WrapperDeployed)
  |-- Optional registration request -> Supabase queue
  |
Maintainer console
  |
  |-- Review submission
  |-- Deploy wrapper if missing (WrapperDeployed)
  |-- List pair for indexing (TokenWrapped -> subgraph template)

Architecture

wraphub/
  frontend/     Next.js app, wallet UX, registry, wrap flows, faucet, decrypt, subgraph reads
  hardhat/      FHEVM contracts, faucet, factory, local mocks, deploy scripts, Hardhat tests
  subgraph/     Sepolia and local manifests, mappings, Graph Node setup
  supabase/     Pair submission queue migrations
  docs/         Architecture, deployment, extensibility, faucet, indexer, and ops guides

Frontend

• Next.js App Router
• React and TypeScript
• Tailwind CSS
• RainbowKit, wagmi, and viem
• TanStack Query
• @zama-fhe/react-sdk and @zama-fhe/relayer-sdk
• Supabase-backed submission APIs
• next-intl for English, French, Korean, and Vietnamese

Contracts

• Solidity and Hardhat with @fhevm/hardhat-plugin
• OpenZeppelin Confidential Contracts and ERC-7984 wrappers
• WrapHubFaucet for gasless Sepolia claims
• ConfidentialTokenFactory for wrapper deployment and maintainer indexing

Indexer

• Sepolia manifest: official wrappers, faucet, and factory dynamic templates
• Local manifest: Hardhat wrappers, faucet, and factory dynamic templates
• deployable to Goldsky or Subgraph Studio

Registry Source Model

WrapHub uses a hybrid registry model.

Source	Meaning
Official registry	Pair registered in the Zama Wrappers Registry
Custom tab	Browser-local pairs, repo seed pairs, or maintainer-listed submissions
Factory wrapper	Confidential wrapper deployed through WrapHub's factory
Indexed pair	Wrapper tracked by the subgraph for activity and metrics

Official pairs come from the Zama registry. Custom pairs are useful for development and maintainer-reviewed coverage, but they are not official until Zama registers them onchain.

Full details: Extensibility Guide.

Deployed Addresses

WrapHub-owned Sepolia deployments:

Contract	Address	Explorer
WrapHubFaucet	0x36294a8eC61f0c6DD441badF489d3eC77eB83C95	Etherscan
ConfidentialTokenFactory	0x43F7F7432ACbbDb6969594Bd591e91Bd861DdeBa	Etherscan

Official Zama registry read by WrapHub:

Network	Contract	Address	Explorer
Sepolia	Wrappers Registry	0x2f0750Bbb0A246059d80e94c454586a7F27a128e	Etherscan

Current Sepolia subgraph:

https://api.goldsky.com/api/public/project_cmq7zytlz55i201y1468xfisr/subgraphs/wraphub-sepolia/v0.0.3/gn

Documentation

Public docs live in docs/:

• User Guide
• Architecture
• Extensibility Guide
• Deployment Guide
• Indexer Guide
• Faucet Operations
• Troubleshooting

Supabase setup: supabase/README.md

Getting Started

Prerequisites

• Node.js 20+
• npm 7+
• a wallet supported by RainbowKit
• Sepolia ETH for gas when testing on Sepolia
• Supabase project values if using Create wrapper registration or the maintainer queue

Install

npm install
cd frontend && npm install
cd ../hardhat && npm install
cd ../subgraph && npm install

Configure Environment

cp frontend/.env.example frontend/.env
cp hardhat/.env.example hardhat/.env

Frontend essentials:

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=
NEXT_PUBLIC_SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
NEXT_PUBLIC_ZAMA_WRAPPERS_REGISTRY_SEPOLIA_ADDRESS=0x2f0750Bbb0A246059d80e94c454586a7F27a128e
NEXT_PUBLIC_SEPOLIA_FAUCET_ADDRESS=0x36294a8eC61f0c6DD441badF489d3eC77eB83C95
NEXT_PUBLIC_CONFIDENTIAL_TOKEN_FACTORY_SEPOLIA_ADDRESS=0x43F7F7432ACbbDb6969594Bd591e91Bd861DdeBa
NEXT_PUBLIC_WRAPHUB_SEPOLIA_SUBGRAPH_URL=https://api.goldsky.com/api/public/project_cmq7zytlz55i201y1468xfisr/subgraphs/wraphub-sepolia/v0.0.3/gn
NEXT_PUBLIC_WRAPHUB_MAINTAINER_WALLETS=
SEPOLIA_FAUCET_ADDRESS=0x36294a8eC61f0c6DD441badF489d3eC77eB83C95
SEPOLIA_RPC_URL=
FAUCET_RELAYER_PRIVATE_KEY=
SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
ZAMA_RELAYER_API_KEY=

Hardhat essentials:

SEPOLIA_PRIVATE_KEY=
SEPOLIA_RPC_URL=
FAUCET_RELAYER_ADDRESS=

Never commit private keys, relayer secrets, or service role credentials.

Run The Frontend

cd frontend
npm run dev

Open:

http://localhost:3000

Useful commands:

npm run check
npm run type-check
npm run lint
npm run build
npm run start

Run Local Hardhat

Terminal 1:

cd hardhat
npm run chain

Terminal 2:

cd hardhat
npm run deploy:localhost

Terminal 3:

cd frontend
npm run dev

The local deployment creates mock ERC-20 tokens, confidential wrappers, a mock registry, a local faucet, and a local factory.

Optional local indexer:

cd subgraph
npm run docker:up
npm run create:local
npm run build:local
npm run deploy:local

Set:

NEXT_PUBLIC_WRAPHUB_LOCAL_SUBGRAPH_URL=http://localhost:8000/subgraphs/name/wraphub/local
NEXT_PUBLIC_CONFIDENTIAL_TOKEN_FACTORY_HARDHAT_ADDRESS=0x0165878A594ca255338adfa4d48449f69242Eb8F

Sepolia Deployment

Deploy WrapHub-owned contracts:

cd hardhat
npm run deploy:sepolia

This deploys or reuses:

• WrapHubFaucet
• ConfidentialTokenFactory

Configure the faucet relayer:

npm run faucet:relayer:sepolia
npm run faucet:status:sepolia

Build and deploy the Sepolia subgraph:

cd subgraph
npm run build
goldsky subgraph deploy wraphub-sepolia/v0.0.3 --path build

Full release steps: Deployment Guide.

Testing

WrapHub ships Hardhat tests for the local contract layer and Sepolia-facing operational contracts.

Run the suite:

cd hardhat
npm run compile
npm test

Current coverage:

Test File	What It Covers
mock-erc20.ts	Mock token deployment, custom decimals, owner-only minting, balance updates
mock-wrappers-registry.ts	Pair registration, ownership guards, duplicate prevention, interface validation, revocation, pagination
wraphub-faucet.ts	Token and relayer configuration, direct and relayed claims, cooldown reads, mint fallback, transfer fallback, disabled tokens, underfunded errors
confidential-token-factory.ts	Wrapper deployment via factory, duplicate rejection, zero-address guards, recordPairForIndexing, and TokenWrapped emission on maintainer list

Latest local result:

17 passing

Run the full monorepo gate before shipping:

npm run check:prepush

That runs frontend checks and build, Hardhat TypeScript build and tests, and subgraph build checks.

Development Standards

Frontend:

cd frontend
npm run check
npm run build

Contracts:

cd hardhat
npm run lint
npm run format:check
npm run build:ts
npm test

Subgraph:

cd subgraph
npm run check

Pre-commit hook:

npm run check:precommit

Security And Privacy Notes

WrapHub improves wrapper discoverability and operational UX, but it does not make confidential token usage invisible.

Users should understand:

• contract addresses, transaction hashes, and indexed public amounts remain visible onchain
• confidential balances require explicit wallet authorization to decrypt
• local custom pairs and maintainer-listed pairs are not official Zama registry pairs unless Zama registers them onchain
• faucet and relayer keys must be protected like production infrastructure secrets
• local Hardhat configuration is for development and testing

This repository is under active development and has not been independently audited.

License

See LICENSE.