Architecture

Covenant is a small set of single-responsibility contracts around one Uniswap v4 pool. The hook is the brain; accounting, custody, and routing are delegated to dedicated contracts.

The contracts

Contract	Responsibility
CovenantHook	The brain. Detects buy/sell, levies the 3% tax, retains the 20% covenant on sells, absorbs the FIFO queue at a 5–20% discount on buys, and settles matured covenants into locked LP. Implements the v4 beforeSwap / afterSwap callbacks.
CovenantQueue	FIFO storage and lifecycle of covenants — amounts, statuses, order. Owns covenant accounting and emits every lifecycle event. Mutations are hook-only. The single address to index.
CovenantVault	Custody. Holds funds as ERC-6909 claims inside the PoolManager. Real value moves are performed by the hook.
CovenantRouter	The user entry point. Wraps swaps and calls the PoolManager's unlock flow; also triggers flushTax after swaps.
CovenantToken	The CVN ERC-20 token (18 decimals).
CovenantMath	A pure library for bps math, discounts, and constant-product buy/sell quotes.

Separation of concerns

The design deliberately splits three things that are often tangled:

• Accounting (who owes what, in what order) lives in the Queue.
• Custody (where the funds actually sit) lives in the Vault, as ERC-6909 claims.
• Value movement (the real swaps, tax payouts, LP mints) is done only by the Hook, through the Uniswap v4 PoolManager.

This is why the Queue can be a clean, indexable source of truth: it never holds funds, it only records state and emits events.

Pool convention

The canonical pool is CVN/ETH with a fixed currency ordering the hook relies on:

• currency0 = native ETH (address(0))
• currency1 = CVN (TOKEN)
• zeroForOne == true ⇒ ETH → CVN ⇒ BUY
• zeroForOne == false ⇒ CVN → ETH ⇒ SELL

Continue with the v4 hook, the heart of the system.