The documentation.

Part I · What it is

1. Summary

Atlas.trade is a Uniswap v4 pool whose fee depends on the size of your trade relative to the usual trade size of this pool. That usual size is called the measure. Nobody sets it: the pool computes it from its own flow, continuously.

A trade within the measure pays the base rate. A trade in excess pays in proportion to its excess, and it lowers the favour, one shared, visible number from 0 to 1000 that multiplies everyone's rate. The favour rises when trades are measured, and it leaks by itself when nothing happens. Its value decides which of the twelve Olympian gods sits on the throne, and each god carries a coefficient: Zeus halves the fee, Ares more than triples it.

There is no end, no draw, no winner. It is a permanent state the pool maintains itself.

What it produces, concretely. On a realistic size distribution, the median rate paid stays exactly the base rate whatever the dispersion of the flow, while the mean rate rises to 1.15% and the largest percentile carries 39% of the whole surcharge. The ordinary trader notices nothing; the surcharge is carried entirely by the orders that move the market.

This is the only design in this family that needs to know nothing about who trades. No address, no hookData, no shared heap, no fallback. The size of the trade and the state of the pool are enough.

2. What this protocol is not

Not a whale shield

A whale can trade whatever it wants, whenever it wants. Nothing is ever refused. The hook never reverts a swap, for any reason: that invariant outranks everything else. The protocol does not say you shall not pass; it says here is the price, it is displayed, it is computable before you sign. An actor who wants to move 20 times the measure at once can. They will pay the cap, and they will have dropped the favour by 110 points for everyone. If you are looking for an anti-dump, this is not one. It is impact pricing, and it is symmetric.

The surcharge does not go to your pocket

The surcharge above the base rate is split half to the LPs, half to the temple. No mechanism pays a holder as a holder. Holding $ATLAS entitles you to no flow.

The favour is not an oracle, and it predicts nothing

The favour measures the past behaviour of this pool and nothing else. It does not say the price will rise. It does not say the token is good. A dull token whose ten traders trade politely will sit under Zeus; a hot token where everyone rushes will sit under Ares. The favour rewards conduct, not quality. Confusing the two is the most likely misreading.

Not an EIP-1559 fee market

A target market says: too many people, everyone pays more. Atlas.trade says: you took four shares, you pay four times. Both mechanics coexist here, Nemesis is individual and the favour is collective, but the collective one is second order: it only exists because someone exceeded, and it repairs itself.

The measure can be manipulated, and the cost is computed

Pulling the measure up to buy yourself margin is possible. Section 24 gives the exact price. It is high but finite, and it is stated rather than denied.

The cap is soft

Above twelve times the measure, the rate stops rising. And an order that lands exactly on that cap can be split inside one block to pay 25% less than the table announces. Not a leak: the arithmetic of a cap, dismantled in section 26. A document that stayed silent about it would lie by omission.

What this forbids writing

• « protects against dumps »: false, see above
• « fees go back to holders »: false
• « the favour is a health indicator »: false
• « big orders cannot pass »: false, nothing is ever refused
• any wording that suggests a return

What can be written, and is true: the rate is fully computable before signing; the median trader pays the base rate; the surcharge is carried by those who move the market; splitting your order inside a block costs nothing more.

3. The principle on one page

The pool holds three numbers. All three are public and readable at any instant.

When you trade, two coefficients multiply the 0.30% base rate:

Nemesis is your ratio to the measure. Nothing else. Under Apollo (×0.76), measure 0.42 ETH, first trade of the block:

Below the measure, nemesis is 1: you never pay less than the base rate, and a tiny trade does not cost less than a normal one, in proportion.

What the favour does

• Measured trade (nemesis ×1): the favour rises by up to 4 points, in proportion to size. A trade at the measure returns 4 points; a quarter of the measure returns 1.
• Excess trade: the favour drops by (nemesis − 1) × 10 points, up to 110 points at twelve times the measure.
• Always, whether anything happens or not: Hestia removes 1 point per minute. The hearth dies if nobody feeds it.

And a single trade at twelve times the measure erases 28 measured trades: thirty-seven minutes of good conduct at one trade per minute. That is the whole protocol.

Part II · The three numbers

4. The measure

The measure is the usual trade size of this pool, expressed on the ETH side. It is 0.42 ETH in the worked example. It is not a parameter; it is recomputed at every trade, from the trades.

The /32 moving average gives inertia: one isolated trade moves the measure by a thirty-second of its gap; it takes about thirty coherent trades to really move it. The clip at four measures is what stops a giant from dragging it: an order of forty measures counts exactly like an order of four. The gods count a giant as four men, no more.

Why the clip, and not something else

Three definitions were tried and measured on simulated flows (log-normal sizes, 120,000 trades). « within the measure » is the share of trades paying the base rate; instability is the coefficient of variation of the measure.

The asymmetric EMA, meant to resist the big, does the exact opposite of its intent: on a tight flow it settles at the 36th percentile and two trades out of three become excess. The symmetric EMA converges to the mean, which big trades drag, and one giant moves everyone's rate. The clipped EMA is the only one whose behaviour does not degrade as the distribution widens, and its instability stays under 21%.

The clip factor was swept: C = 4 keeps 67% of trades within the measure with only 15.1% paying more than twice base, and past 4 there is nearly nothing left to gain. It also has the advantage of being sayable: a giant counts as four men.

The measure at start

At the first trade there is no measure yet, so it is initialised, and it is floored forever. The floor is not cosmetic: without it, a pool that sees only dust for one hour would watch its measure collapse toward zero, and the first normal trade to arrive would pay the cap.

What the measure is not

Not the median, which would need history. Not the mean, which the tail drags, and the tail is exactly what must not set the norm. Not a volatility: it looks at neither price nor spread. Not the liquidity: the measure says what is done, not what could be done.

5. Nemesis, what your trade pays

where s is the size of your trade and V the volume already traded in the current block, both directions, converted to token1 like everything else.

Why 2V + s and not simply s

The heart of the protocol, in one line: without the V term, splitting your order would erase the bill. A rate proportional to size makes you pay the square of size, so twelve orders of size 1 pay twelve times base while one order of size 12 pays one hundred and forty-four times. A protocol built on that dies at the first line of a router's code. The 2V + s term is the marginal rate at the middle of your order, and it has an exact property.

The identity that holds everything

Whatever the partition. An algebraic identity, not an approximation. Numerical check, an order of six measures inside one block:

The first three splits cost exactly the same. The +0.69% on crumbs smaller than the measure comes from the lower stop: every crumb pays the floor rate. Section 26 treats both stops in full.

How a trader computes the rate before signing

Five reads, zero assumptions. That is the condition for the hook's promise to never revert a swap: you may only refuse what the caller could predict, and here there is nothing to refuse at all.

The two stops

At the bottom, nemesis = 1. Never below the base rate: a pool whose fee dropped to zero for small orders would be a magnet for spam, and here a magnet for free favour manufacturing. At the top, nemesis = 12. An unbounded rate is a disguised revert (at 40% nobody passes: the door was closed while pretending it stayed open); a capped grid reads, an asymptote does not; and beyond the cap, slippage does the work: an order at forty measures crosses the book, and price impact exceeds fees by an order of magnitude.

The clear table, Apollo ×0.76, measure 0.42 ETH, first trade of the block

Note the 21 ETH line: the rate is capped, but the bill keeps rising, because it applies to a larger base. The cap bounds the rate, never the invoice.

6. The favour

An integer from 0 to 1000. One for the whole pool. Visible. It represents nothing but itself: a counter that rises when trades are measured, falls when they are not, and leaks when nothing happens.

The three movements

The damage saturates exactly where the rate saturates: beyond twelve measures neither the price nor the anger grows. Same bound, and not by chance, see section 25. The leak is applied lazily by the first trade that follows, from the timestamp of the last passage: no loop, no external call, no reward to trigger it.

Why the favour is collective

Because the impact is. When an order moves the price by 4%, it does not move its own price, it moves the price: the next ten traders buy dearer and the LPs carry an unrealised loss. The effect is common; the pricing that reflects it must be too. There is a cost to this choice and it is named: an honest trader can pay more because of somebody else. That is the price of a shared state, and also what makes the favour worth watching.

The trap: the favour in whole points does not work

Written naively, grace = 4 × min(t, m) / m is zero in integer arithmetic as soon as t < m/4. Measured over 180,000 log-normal trades: 23.3% of trades return exactly zero points and 13.9% of all grace disappears. And that quarter is exactly the population the rule wanted to reward, the small orders that are within the measure. The fix is one line: store the favour in thousandths of a point (0 to 1,000,000) and display whole points. The general rule: any proportional reward stored as integers has a size below which it is zero, and that size is almost always bigger than believed.

The favour locks nothing, entitles to nothing, cannot pass below 0 nor above 1000 (both saturate), and has no retroactive effect: an executed trade is never recomputed when the favour moves.

7. The twelve thrones

The favour seats the god, and the god sets the collective coefficient. These are the canonical Twelve Olympians, the Dodekatheon: Hades was never among them, he reigns elsewhere; Hestia no longer is, she gave her seat to Dionysus. The order runs from most generous to most severe, and it follows temperament, not power: an hierarchy of mood, and it reads.

The bands are not equal. The last band is the narrowest and the most severe: a pool under Ares is sixty points from climbing out, fifteen measured trades. Deliberate: it must be easy to leave the bottom and hard to fall back, not the reverse.

The progression. Zeus to Hermes ×2.00, Hermes to Ares ×3.20, Zeus to Ares ×6.40 on the collective coefficient alone. Multiplied by Nemesis, the total gap between the best and worst possible rate is 0.15% to 9.99%: ×66.6. The global cap of 9.99% only ever bites under Ares, for orders past 10.41 measures; eleven of the twelve regimes never meet it.

The full fee table

Rate in percent, per regime and nemesis. Base 0.30%. The star marks the 9.99% global cap.

Two things read off this table, both true. The ×12 and ×20 columns are identical: the top stop, the rate stops rising while the bill keeps growing on a larger base. And a single cell carries the star, the bottom-right corner: Ares past ×10.41. Eleven regimes out of twelve never meet the global cap. Below the measure the ×1 column applies unchanged: the bottom stop, never less than the base rate.

Part III · The money

8. Where the fee goes

Why the LPs get half the surcharge: they are the ones taking the impact; paying them half is direct compensation, in the same transaction, for the damage just taken. Why the temple gets the other half: a surcharge fully paid to LPs is fully dissipated, and nothing is left to hold the flame in quiet times; the temple is the protocol's memory. Why no burn: burning the temple's share under Ares was considered and rejected. The protocol needs its treasury precisely when the favour is low; destroying it then would cut the water during the fire for the beauty of the image.

Technically: the LP fee is returned by beforeSwap with the override flag and stays in the pool; the temple's part is taken by a BeforeSwapDelta and pulled to the hook with poolManager.take, which is why the hook needs the returns-delta permission. The treasury has one exit: the flame. No withdraw function, no treasury address, no multisig, no onlyOwner.

What each trader pays

Simulation over 75,000 trades after warm-up, log-normal sizes, Hermes regime, clipped measure:

The median rate is exactly the base rate in all three regimes. Not roughly: exactly 0.30%. The gap between median and mean is the protocol's signature: a minority pays a lot, and the top percentile finances up to 45% of everything levied above the ordinary rate.

In practice: a retail trader moving 0.3 ETH on a 0.42-measure pool pays the base rate and needs to know nothing. A fund moving 20 ETH pays the cap in one shot, or spreads over a few blocks and pays the base rate. The protocol forbids nothing; it hands over a bill and a calendar, and lets them choose.

Buy / sell symmetry

The rate is identical in both directions; the hook reads the direction only for unit conversion. A pool taxing sells more than buys is a mousetrap: wide entrance, narrow exit, visible at first glance on the contract. The measured/excess axis is orthogonal to direction and does not lie about what it is: it prices impact, and a big buy moves the price as much as a big sell.

The cost to LPs, the trade-off named

What LPs lose: fees of the large orders that go elsewhere. What they gain: half of the surcharge of those who stay, plus, mainly, a reduction in arbitrage loss, since a book-crossing order leaves positions on the wrong side of the price. Which branch wins depends on flow composition, and nobody can know before measuring, so the protocol is instrumented for the answer: the register records volume per nemesis band, enough to reconstruct what passed and what left. That is the only honest position: a hypothesis, not a proof, and the published instrument to test it.

Part IV · The limits

9. What the hook cannot do

• The hookless pool. Anyone can spin an ATLAS/ETH pool without the hook. True of every hook protocol. The only defence is that the canonical liquidity lives in the hooked pool and aggregators route where the depth is. Said plainly: a determined actor can build their own pool; they will find less liquidity there, hence more slippage. The protocol does not forbid it, the market discourages it.
• Aggregated routing. An aggregator can split an order between pools. The hook sees only its share and prices it correctly, which is the desired behaviour: the protocol prices the impact it takes, not the trader's intent.
• MEV. No sandwich prevention, no reordering, no private mempool. One free property though: the sandwicher pays the fee twice, both legs inflate V, each makes the other dearer. Not a protection: a tax. Details in section 27.
• Gas. On very small orders gas dominates the fee, and the protocol can do nothing about it.
• It cannot know whether an order is economically a buy or a sell, cannot tell a market maker from a dumper, knows no external price, and cannot act between two swaps: everything is lazy, triggered by the next passage.

10. Attacks, and what they cost

Pulling the measure up

If the measure rises, my excess shrinks: an actor planning to move 20 ETH would like the measure at 5 ETH first. The first attack anyone thinks of, and it is real. The clip bounds every trade's contribution, so multiplying the measure by k takes ln(k)/ln(1.09375) trades of four measures each, every one paying the ×4 excess rate and 30 points of damage.

Full simulation from Zeus, measure 0.42 ETH, 28 consecutive trades at four measures:

The attacker multiplied the measure by twelve and multiplied by 3.9 the very base rate they wanted to reduce. Three stacking reasons it fails: the attack pays for itself (raising the measure requires doing exactly what the protocol prices); it destroys what it seeks (the favour collapses from 1000 to 160); and the book kills it: 202 ETH through a 0.42-measure pool is several times the liquidity, slippage exceeds fees by one or two orders of magnitude. The fees are the visible and cheapest part of the bill.

What does work, and is accepted: a patient actor raising the measure slowly, one 4× trade from time to time, letting the favour recover in between. It takes hours, pays the excess each time, and supplies real volume to the pool along the way. We call that an attack because we are hunting for attacks. It is market making.

Dropping the favour

Gain nothing yourself, just make the pool expensive for everyone: pure griefing. Full simulation from Zeus, successive trades at twelve times the current measure, accounting for the measure and the coefficient both rising:

What keeps it from being worse is a decision that looked decorative: the damage saturates exactly where the rate saturates. If damage kept growing with size while the rate capped, one single large enough trade would zero the favour while paying at most the cap: griefing would cost one order instead of ten.

And the real wall again: 185.6 measures is, for a pool whose measure is 1% of liquidity, nearly twice the entire liquidity pushed through the book. Slippage makes the operation absurd before the fees even matter. The fees are the computable part of the defence; the book is the rest, and it is bigger.

Splitting, the attack that is not one

Without the V term the protocol would be dead on arrival (section 6). With it, the identity telescopes and splitting inside a block is neutral. The stops [1 ; 12] break the linearity of the marginal rate at the edges, hence the identity, and the full gap table is:

At the bottom, splitting costs more: every crumb pays the floor, and dusting an order at the measure into twelve pieces costs 25% extra. The right direction: it discourages micro-order spam, otherwise the cheapest way to manufacture favour. At the top, splitting costs less, at most 25% exactly at twelve measures, decreasing beyond. Read it the right way round: the correct price, the integral of the marginal rate, is the split order's price. It is the monolith that overpays, because the cap applies the maximal rate to its whole size including the half that alone would not have reached it. And splitting inside a block is free and available to everyone: not a flaw a few exploit, an unfavourable rounding for whoever does not bother. Capping on the block's cumulative volume instead would fix it at the price of extra state, to refund the population already paying the most; not done.

Across blocks: V resets each block, so spreading an order over twelve blocks, two and a half minutes, makes it genuinely much cheaper. That is the point. Nothing in excess does not mean do not trade much; it means do not trade much at once. An actor spreading over two minutes has reduced their market impact, so they must pay less. The protocol rewards exactly that; the opposite would push everyone to strike at once.

MEV, the sandwich, the first trade of the block

The sandwich is not prevented. Three measurable effects, though: the sandwicher pays the fee twice; the front leg inflates V so the victim's nemesis rises, a perverse effect that must be named, the sandwich costs the victim more here than elsewhere; and the back leg pays the cumulated V of the other two, the highest marginal rate of the three. On equal legs the marginal rates are proportional to 1s, 3s, 5s: the sandwicher pays 6 shares, the victim 3. The sandwicher pays twice what the victim pays, but the victim pays three times what they would have paid alone. Not a protection: a tax on the attacker and on the victim, and it must be said that way.

The first trade of a block is privileged: V = 0, lowest marginal rate, a position of value, therefore MEV in the proper sense. Accepted, because every alternative is worse: a rate independent of intra-block order would reopen free splitting. The advantage is bounded: first pays s/m, last pays (2V+s)/m, a factor of six on a three-measure block, twelve at the cap. No private mempool, no batch auction, no commit-reveal, no TWAP, no oracle: their complexity exceeds what this protocol is for.

11. What stays open

• The twelve coefficients are arbitrary. The ×0.50 to ×3.20 scale gives a 6.4 gap and a fixed point at Hermes; nothing says it is the right scale, only a live pool will, and there is no governance to change it. A frozen bet.
• The one-point-per-minute leak is arbitrary: 16 h 42 of full descent, perhaps too slow for a busy pool, too fast for a quiet one.
• Whether the protocol costs or pays the LPs is unknown. The main open question; the instrument to answer it is in place.
• Coordinated adverse flow is not modelled. All simulations assume independent sizes.
• Aggregator interaction is unknown. One that integrates the rule will split automatically, which is desirable; one that does not will send capped orders unknowingly. No leverage over either.

The risks

• Design: the calibration is frozen. Twelve coefficients, one leak rate, one clip factor, one time constant, two bounds; none modifiable, because there is no governance. If the calibration is bad it stays bad. The price of no admin, next to its benefit: nobody can change the rules on you.
• Adoption: the protocol asks to be read. A trader arriving blind sees a rate they did not expect; a bad surprise on a fee is what loses a user for good. The main risk, and it is one of presentation, not mechanics: the site has one job, showing the rate before.
• Technical: the hook sits in the critical path. Any beforeSwap bug breaks every swap. Mitigations are in the code, no revert, no unguarded division, no bare subtraction, and in the tests.
• Economic: the LPs may lose. The hypothesis is that reduced arbitrage loss offsets the discouraged flow. It is not proven.
• Regulatory: low. No bet, no lottery, no return, no promise: a fee schedule applied to a trade. The only vigilance zone is wording, per section 2.
• Narrative: nothing happens. No resolution, no winner, no event. Assumed, and the only counterweight is the record of time spent at the top, the one number of the protocol that can be beaten.

Reference

A. Constants

FLAMME_PAR_SEC = FUITE_PAR_SEC is not a coincidence and must never be changed separately: it is what guarantees the temple can never raise the favour. And 1000/60 = 16 in integer division, 0.96 point per minute rather than 1.00: the 4% gap is assumed and documented here rather than fixed with a finer scale, 17 h 22 of full descent instead of 16 h 40, and no property depends on it.

B. Glossary