Architecture

zk-pad is a set of Solidity contracts on BNB Smart Chain, a TypeScript SDK, three off-chain services (relayer, attestor, indexer) and a web app.

Components

Layer	Component	Path	Role
Contracts (launch)	ZkPadFactory	contracts/src/ZkPadFactory.sol	Deploys tokens, pools, locked liquidity, dev buy, MEV module
	ZkPadToken	contracts/src/ZkPadToken.sol	Fixed-supply ERC20
	ZkPadHook (+ ZkPadHookBase)	contracts/src/hooks/	Infinity CL dynamic-fee hook: fee per direction, 25/75 split, locker-only liquidity
	ZkPadLpLocker	contracts/src/lockers/	Owns liquidity forever; collects, converts and deposits LP fees
	ZkPadMevDescendingFees	contracts/src/mev/	Anti-sniper descending fee
	ZkPadSwapRouter	contracts/src/periphery/	Minimal exact-in / exact-out router for the UI
Contracts (vault)	FeeVault	contracts/src/vault/	Opaque beneficiary accounts, EIP-712 owner actions, binds, fallback
	RailgunShieldAdapter + ShieldSender	contracts/src/adapters/	USDT-only shield into Railgun via per-beneficiary proxies
	QuoteRegistry + route executors	contracts/src/consolidation/	Quote allow-list (Tier 1 / Tier 2), USDT routes (Infinity CL, PancakeSwap V3), Chainlink bounds for creator-triggered consolidation
Off-chain	SDK @zk-pad/sdk	packages/sdk	Ids, claim links, EIP-712, hints, launch math, Railgun data, service clients
	Relayer	services/relayer	Validates, simulates and submits signed vault actions (claims pay through relayerFee, other owner actions through a fee-only claim); fetch-everything account index
	Attestor	services/attestor	Salted commitments (paid handle lookups), OAuth, BindOwner signatures, hint index, event-sourced account index, veto watcher
	Indexer	services/indexer	Ponder indexer: tokens, trades, candles, holders, activity, beneficiary dump
	Web app	apps/web	Next.js dApp for traders, creators and beneficiaries

Contract relationships

Main flows

Launch

See the sequence diagram in how it works. Key invariants:

• only the hook, called by the factory, can initialize a zk-pad pool (beforeInitialize reverts for everyone else; Infinity skips the callback when the hook itself initializes);
• the locker places the whole supply and SupplyNotPlaced reverts the launch otherwise;
• the dev buy runs before the MEV module is armed.

The factory checks the quote allow-list (setQuoteToken, mirrored by the QuoteRegistry). The launch wizard lists every factory-enabled quote and overlays the registry's consolidation data; quotes the registry does not list can still be launched, without USDT consolidation.

Swap and fee collection

Claim

Design references

• docs/BUILD_SPEC.md: binding decisions.
• contracts/PORTING.md: every deviation from Clanker v4.
• docs/ARCHITECTURE.md and docs/THREAT_MODEL.md: the audit-facing versions of this section.
• docs/research/*.md: evidence behind each decision.