Custom hooks and builder royalties

A V4 hook lets a pool apply extra trading rules. As a creator, choose behavior that serves your market; as a builder, develop a useful design for review and potential reuse by other launches.

What you can choose today

A hook is a contract that gives a Uniswap V4 pool additional rules. Instead of every pool behaving the same way, its hook can shape a specific part of the trading experience.

Black Market's current hook handles a chosen hook fee, records price history, and applies the creator's choice about whether others can add liquidity after opening. Each pool gets its own hook, even when the pool contains several liquidity ranges.

For example, a creator who wants other providers to contribute depth can allow outside liquidity. Those providers retain withdrawal rights over their own positions, while the launch's initial positions stay permanently locked. Choose the LP fee and hook fee separately, then compare their cost to traders and the net fee income left for the launch.

Why custom designs matter

Suppose a creator wants a fee that responds to market conditions instead of staying fixed. A reviewed custom design could provide that behavior for several launches, avoiding a separate pool implementation for each creator. The source's Surge reference design explores adjusting the charge using the pool's state before a trade.

Surge is a proof of concept, not an offered mainnet choice. The current mainnet template is fixed-fee. New designs are reviewed before becoming launch options.

Prepare a design for review

1. Build a concrete hook. Describe what it does, who it helps, and the settings a creator can choose.
2. Submit it for review. Include the source, a reproducible build, integration tests and proposed author terms. Review covers the full implementation and how it works with launch liquidity, fees and price history.
3. Agree the approved version and author terms. The reviewed design must be registered before creators can select it; building or submitting it does not make it available.
4. Share in actual income. A creator selecting an admitted design chooses the applicable royalty rate. Payment depends on its market earning and collecting eligible fees.

The developer guide identifies the source-level authoring and admission references. Review is required for each design; submission is not a promise of acceptance.

How royalties work

A hook author can receive part of the owner's fees earned by the market using their hook. This does not add another trading fee or take money from the launch's rewards or burn allocation.

For example, suppose the owner allocation attributable to your hook's market is 100 units after the treasury share and collection bounty. At a creator-selected 10% author royalty, you receive 10 and the owner retains 90. Other markets' owner income is outside that calculation.

Payments stay in the asset earned. Calculations use smallest units, round down when attributing income to a market, then round down again for the author share. Rounded-away units remain in owner income, not an extra author payment.

The deployed registry allows an author rate of up to 24% of the applicable owner fees, while each approved design can have a lower limit. The current fixed-fee template has zero author royalty. The limit is not a 24% charge on trades, and royalties are not automatically enabled by choosing a hook.

What creators should consider

Choose a hook for the behavior it provides, then review its trading fees and any author share. A royalty supports the builder but reduces the owner fees you retain from that market. It does not reduce the rewards or burns you selected.

A pool keeps the rules chosen when it opens. A newly registered design does not replace the hook in an existing pool.

Receiving author earnings

Author fees are credited when the launch's fees are collected. A claim sends them to the author's registered payout wallet. Your author identity stays the same even if that wallet changes.

The current payout controller or registry administrator can update the payout wallet, including where already-credited earnings are sent. This is distinct from the token creator transferring their own fee rights.

Choose the fee and reward split or continue with the hook-author reference.