> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyfi.markets/llms.txt
> Use this file to discover all available pages before exploring further.
# How It Works
> Architecture and trade flow
HyFi is a combination of a CEX and a DEX. Liquidity is only supplied by professional MMs, effectively making HyFi a platform for propAMMs. From the perspective of MMs, they only interact with HyFi's CEX-like offchain orderbook which is compressed by nature. That orderbook is aggregated and put onchain every block. From a trader's perspective, they trade with the aggregated compressed orderbook onchain in the same way they'd trade with a regular AMM.
1. MMs constantly update their orders in the HyFi compressed orderbook offchain for free
2. every block HyFi aggregates the compressed book and updates the contract with an ID for that book's snapshot
3. traders trade against the onchain compressed aggregated orderbook, emitting a trade event with the trade info and orderbook ID
4. HyFi reads the taker trades and the orderbook ID which they interacted with, then looks at the snapshot of that book stored offchain to figure out which orders were traded with, and then update the balances of those MMs and charge fees if applicable
## Compression
In the past, fully onchain orderbooks have been attempted, but they always failed due to the cost of each maker having to manually update their orders. Despite RFQ systems existing for a while, the vast majority of trading is still done onchain, indicating that's the preference of users. How can we get the best of both and enable users to trade onchain but with the CEX-grade pricing that RFQ offers?
The less data that's onchain, the more economically feasible an orderbook-style system can be. A trader only cares that:
* they receive their output tokens immediately
* the trade has the best price **at time of execution**
Given those constraints, we can shave away everything that's not needed to be onchain:
* which MM's orders were impacted by a trade since pricing only cares about the aggregate
* MM's adding/cancelling individual orders onchain
* fees being charged onchain
* all ticks beyond the top \~100 since most ticks won't be used before the next book update
* the 'step size' of liquidity can be constrained to multiples of larger amounts e.g. 1 ETH - only professional MMs will be makers so we don't need to consider retail order amounts
All of this allows us to greatly reduce the data so that the onchain book just consists of 100 ticks, where each tick is represented by an 8 bit `uint` . The maximum liquidity per tick is 255, which, if each tick is 1 ETH, means the max liquidity per tick is 255 ETH. This allows the whole buy or ask side of the book to be stored in only 4 storage slots onchain instead of 100s-1000s like in the past.
Note that the unit of liquidity (the 'step size' for say ETH can be set to anything - 0.1 ETH or 2 ETH etc. - it can evolve over time and will be coordinated with MMs, but this kind of pair config will not be updated every time the book is updated.
When an orderbook update occurs, it includes the price of the top bid and ask and the new liquidity for the 100 nearest ticks for each side. The tick width is pre-configured per pair so that when a taker walks the book, it starts from the tip price (or the last traded price) and knows what the price of each subsequent tick is. Generally the tick width will be set to whatever it is on common CEXes to make it as similar as possible to other CEXes for MMs to use their existing infra.
For example for ETH-USDC if the step size is 1 ETH, the tick width is \$0.01, and the tip of the ask book is \$2,000.01, then the cumulative liquidity can look like:
Then if a maker moved their 1 unit of liquidity order from \$2,000.01 to \$2,000.02, and there are no other changes, then the onchain book was updated, it would look like:
The data in this input only consists of:
* the new ask tip price of \$2,000.02
* an array of 100 8-bit numbers that represent the liquidity for each tick slot
This allows updates to only use 4 total storage slots per side, which only costs 40k gas for the whole book in total, enabling cheap frequent updates that can accommodate many MMs with deep liquidity - **an orderbook is now economical on ETH mainnet for the first time ever.**
## How a trade works
As a trader, buying works just like a CEX, but there are some nuances on the MM side. When a taker trade is received, it starts from the tip of the orderbook side it's using, and walks the book until the order is satisfied. However, the step size does not impact the taker trade - trades can be for any amount. E.g. at the start of the example above where the tip of the ask book is \$2,000.01 and there's 1 ETH of liquidity in that tick, and a trade comes to buy 1.8 ETH:
* the trade will buy 1 ETH at \$2,000.01 from tick1, and still have 0.8 ETH left to buy
* it will continue to tick2, see it has no liquidity
* it will continue to tick3, and buy 0.8 ETH at \$2,000.03
* the trade concludes and the contract saves the current tick (tick3), and how much liquidity is left (0.2 ETH)
So far, this is pretty much the same as a CEX. If there is another buy before HyFi updates the book, then it just continues from where it left of in tick3.
But, when the orderbook inevitably updates, there will probably be some liquidity 'left over' in the tick, and observant readers will notice that it conflicts with the step size. HyFi handles this by removing liquidity that's under the step size. For example if the above trade (buying 1.8 ETH) occurred and there is 0.2 ETH left in tick3, then the book updated without MMs doing anything, there would be 0 liquidity at the \$2,000.03 tick, because a partial step size cannot be represented in a compressed form.
However, in reality, like when interacting with a CEX, MMs will be constantly querying their current balance and updating their liquidity accordingly. If the 1.8 ETH buy happened in block N, the likely sequence of events would be:
* trade occurs in block N
* HyFi sees the trade and updates its internal CEX, adjusting the balances of the MM
* the MM queries HyFi for their balances and recent trades, and sees the trade
* the MM readjusts their orders
* HyFi updates the onchain book in block N+1
There is a tradeoff in this system for MMs that, out of the capital they have deposit, they will generally only be able to have \~99% of it deployed in live orders - it can only ever be 100% if the total amount they have deposited is an exact multiple of `step_size` . It is a quirk that's the result of there being no `step_size` for users onchain, but having a `step_size` offchain on the CEX that's necessarily for the system to reduce data and be economical.
## Fees
HyFi currently has 0 fees to encourage growth, but will charge fees in the future - but it will be low enough that it's still far cheaper to MM on HyFi compared to the costs associated with running an independent propAMM.
Fees are not charged to users in their trade tx, they are charged at the level of the CEX to the MM that was the maker in that trade. Obviously, these fees still get passed to users in the form of slightly worse prices which are economically the same, but it allows the onchain tx to be extremely cheap in gas costs since there's less computation, making HyFi even more appealing to users.
## Block Builders
On Ethereum, HyFi uses block builders like Titan and others to only push updates to the book when a taker trade has been found, to guarantee the taker executes with the freshest prices. On L2s, the gas costs are cheap enough that HyFi is constantly updating the book whether there are incoming taker trades or not, since there aren't equivalent services.
## Is HyFi decentralised?
Not fully — but **for traders it is non-custodial and permissionless.**
The book update mechanism is centralised currently. Perhaps that can change in the future, but centralisation enables things to be faster and cheaper, which translates to better prices for traders, and the unfortunate reality is that 99% of users just want the best prices and don't care about decentralisation. However, users don't need to trust HyFi:
* the smart contract guarantees the user either gets the minimum output they specify, or the tx reverts
* tokens don't need to first be deposited somewhere
For MMs, they have to trust HyFi since their interaction is essentially the same as a CEX.