Holder rewards

Who earns

On every trade, the holder part of the fee (0.5%, 1% or 2% of the trade, depending on the tier) is shared at once among all tokens that are earning, in proportion to balance. Rewards are paid in the quote asset.

Addresses that are part of the market's machinery never earn: Uniswap's PoolManager (which holds the pool's own tokens), EtherFamily's hook, fee escrow, factory and token deployer, the token contract itself, and the zero and dead addresses. Every other address, wallet or contract, can earn.

Earning starts in the next block

Tokens that come out of the pool, which includes every buy, are first pending. They become active, and start earning, at the first reward-related action in a later block: any transfer, trade fee or claim of that token. Consequences:

• A buyer earns nothing from the fee of its own buy.
• A buyer earns nothing from trades in the same block as its buy, so buying right after a large trade to share its fee does not work.
• Tokens taken out of the pool and returned within one transaction never earn, however they move in between.

The token page shows, for a connected wallet, how many of its tokens are pending and from which block they earn.

Selling and transferring

• A seller keeps everything its tokens earned while they were active, including earlier in the same block.
• Sending active tokens to another wallet keeps them earning without interruption. Sending pending tokens keeps them pending for the receiver; a transfer moves pending tokens first.
• Selling or sending tokens to one of the excluded addresses removes them from the earning supply.

When nobody holds a whole token

When fewer than one whole token is active, the holder part of a fee cannot be shared sensibly. It waits, and is released at the next fee or claim that finds at least one whole token active, to the tokens active at that moment. Tokens bought in the block of the release get none of it. Nothing is ever paid to EtherFamily or to an admin.

Claiming

• A holder claims through the token contract. The payment comes from EtherFamily's fee escrow, in the quote asset, straight to the holder.
• Anyone may trigger the claim of an address that has no code; the reward is always paid to that address itself. A batched push can pay up to 200 such addresses at once.
• A holder can send its own rewards to another address. For stock quotes, EtherFamily checks both addresses against the issuer's lists before paying elsewhere.

Smart contracts and delegated accounts claim for themselves:

What remains possible

These effects of the design are documented rather than claimed away.

• Borrowed tokens. A holder that borrows active tokens from another contract for one transaction (a flash loan from a lending market or another pool) earns the lender's share of that transaction's fees. Other holders lose nothing; the lender does.
• Waiting rewards. If every holder has left, the next holder of one whole token across one block boundary can receive everything that was waiting.
• Concentration. Rewards follow balances. With a creator first buy, the creator is the only earning holder during the release block and receives most of the holder fees of the first blocks Model. The opening window
• Other pools and contracts. Tokens in other Uniswap v4 pools sit in the PoolManager and never earn. Uniswap v2 and v3 pools and other contracts earn like any holder but nobody can claim for them; unless they claim themselves (v2 and v3 pools cannot), their rewards stay in the escrow for good.
• Rounding. Integer rounding leaves a few of the quote's smallest units per account in the escrow, unclaimable.

The token page and the claims page show the concentration of the earning supply:

How the design was checked

The rules were written as an exact integer model and checked against an independent reference that computes every holder's entitlement from scratch: named scenarios (a new holder, a seller, a pool flash, a back-run, waiting rewards, the creator's first buy) and three randomized runs of 4,000 operations, with every invariant checked after each operation Model. The contracts must reproduce the model's test vectors exactly; they are not deployed.

Cost: a reward-paying token costs more gas per transfer than a plain one, estimated at 10,000 to 30,000 gas Hypothesis until measured.