LooksRare Protocol Overview
What is the LooksRare's V2 Protocol?
LooksRare's V2 Protocol consists of a hybrid off-chain/on-chain system where taker orders are matched with maker orders to execute trades for NFTs.
It is a non-custodial exchange where orders require approval of the tokens (fungible and non-fungible) being transferred in a trade. Off-chain orders ("Maker orders") are EIP-712 signatures that are stored off-chain.
A transaction consists of a bilateral exchange of either ETH or an ERC-20 token against one or multiple NFT tokens (e.g. ERC-721, ERC-1155) with a specific amount at a specific price.
In the protocol, the bid user spends fungible tokens to acquire NFT assets. On the other hand, the ask user sells NFT assets for fungible tokens.
Trades exist as a combination of taker/maker and bid/ask.
MakerBid is a
Maker object with the
quoteType set to 0 (Bid) and the
MakerAsk is a
Maker object with the
quoteType set to 1 (Ask).
TakerBid are standard
Taker objects defining the
recipient of the asset (if matched against a
MakerAsk) or funds (if matched against a
- MakerBid (
Maker) — a passive order that exists off-chain where the user wishes to acquire an NFT using a specific ERC-20 token.
- MakerAsk (
Maker) — a passive order that exists off-chain where the user wishes to sell an NFT for a specific ERC-20 token.
- TakerBid (
Taker) — an order that is executed on-chain and matched against a
MakerAsk, e.g., the taker accepts the offer from the maker and buys the NFT for the ETH or the ERC20 token specified.
- TakerAsk (
Taker) — an order that is executed on-chain and matched against a
MakerBid, e.g., the taker accepts the offer from the maker and sells the NFT for the ETH or the ERC20 token specified.
See Order Types for more details on each order type.
Order matching relies on the concept of execution strategies that define the rules of how trades must be matched: (1)
amounts, (4) whether the trade invalidates the maker order (
isNonceInvalidated). The strategies are mapped with a
LooksRare's execution strategies enable the integration of customizable sets of rules, which can be expanded over time to effortlessly incorporate new functionalities, such as dutch auctions, into the protocol. A user can make use of a certain strategy by setting the
strategyId in the
Maker object to the id of the desired strategy. Then the
ExecutionManager uses the
strategyId to route the order details to the correct strategy for execution.
Each strategy consists of a contract function that takes two order inputs (
TakerAsk) and returns a 4-tuple:
- The total
priceof the transaction.
- An array containing the
- An array containing the
amountsof each token id being transacted (ERC-721: 1 /ERC-1155: 1+).
isNonceInvalidatedflag defines whether the trade invalidates the maker order.
In the Solidity codebase, standard transactions use the native strategy with
strategyId = 0. Standard transactions means the maker decides the price, the itemIds, and the amounts. The transaction is atomic and it cannot be partially filled.
LooksRare's execution strategy design can allow for more advanced and innovative order types, such as:
- Collection orders — a
MakerBidcan be executable against any
TakerAskwithin a designated collection (e.g,. "I wish to buy an asset from the BAYC collection for 40 WETH").
- Trait-based orders — (pending implementation) through the use of cryptographic proofs (e.g,. "I wish to buy an asset from the BAYC collection for 55 WETH if its metadata for hat is a party hat").
- USD based listings — (pending implementation) enable the user to define the price in USD and receive the equivalent amount in ETH at the time of the sale. This is achieved with the use of the Chainlink ETH/USD price oracle to auto-convert at the transaction time when the
TakerBiduser executes the transaction.
- Listing relative to the floor price — (pending implementation) a strategy where the user can list an asset to be always a certain amount away from the floor. This is achieved with the use of the Chainlink NFT Floor Price Feed to calculate the final sale price based on the premium or discount defined by the
- Bid for assets with an id within a certain range — (pending implementation) a strategy to limit the
MakerBidvalidity to a certain range of token ids.
Protocol and creator fees
On each trade, trading fees are taken from the execution price and can exist as (1) protocol fee and/or (2) creator fee. Protocol fees are always deducted from the final amount before transferring the profit to the Ask.
We currently have a 0.5% protocol fee and a 0% creator fee.
Protocol fees are present at the strategy level and include the following parameters:
standardProtocolFeeBp: standard protocol fee for a strategy (in basis point).
minTotalFeeBp: minimum total fee (in basis point).
maxProtocolFeeBp: the maximum boundary if it is adjusted.
Creator fees can be assigned a specific on-chain logic that exists as a stand-alone contract.
- Creator rebate model: a fixed royalty applies (e.g. 0.5%)
- Full royalties model: full royalties apply
Two sources are used to determine creator fee recipients:
- LooksRare’s RoyaltyFeeRegistry
There is no “slippage parameter” but instead an adjustable limit is set by the owner at the protocol level. If the creator fee is higher than a defined percentage, it reverts.
The protocol fee parameters for a strategy can be updated by the protocol owner but the
newMinTotalFeeBp) must be inferior to the
maxProtocolFeeBp defined initially at the time of the strategy deployment.
What is the core architecture?
The LooksRare Protocol consists of a stand-alone contract (
LooksRareProtocol) that coordinates with other smart contracts designed to provide instructions on how trades must be executed, verifies the validity of strategies and currencies, whether collection rebates must be paid (and to who), and how tokens must be transferred.
LooksRare's v2 Protocol core architecture consists of:
- Currency manager (`CurrencyManager) — handles an allowlist of currencies that are valid for transactions within the protocol.
- Execution manager (
ExecutionManager) — handles the execution by routing the maker order and taker order to the correct strategy implementation.
- Nonce manager (
NonceManager) — handles the nonce logic that is used for invalidating maker orders that exist off-chain.
- Transfer selector for NFT contracts (
TransferSelectorNFT) — handles the logic for transferring assets based on the
assetTypeand for supporting non-compliant asset types or new standards.
- Creator fee manager (
CreatorFeeManager) — provides a stand-alone logic that tells if creator fees should be collected and what amount. It supports ERC-2981 ("NFT Royalty Standard") and our own royalty registry (
- Affiliate manager (
AffiliateManager) — handles the management of affiliates for the LooksRare protocol.
Other design decisions
LooksRare v2 Protocol's modular design allows the upgradeability of specific parts of the exchange without any need for proxies, circuit breakers (e.g., the possibility to discontinue a strategy or a currency), and the rollout of new features continuously (e.g., support of new order types).
Advanced cancellation features with a triple-nonce system
- Global user bid/ask nonces — each user address is mapped to one ask nonce and one bid nonce. The nonce on the maker order struct must match the signer's value on the chain. This can be used for canceling all pending maker bids or/and pending maker asks.
- Order nonce — used to know whether an order with this nonce can be filled, is being filled or has been filled/cancelled. If an order has started "partial filling", it is impossible to execute other orders sharing this order nonce.
- Subset nonce — comes in addition to the order nonce, and serves a different purpose. They can be used to group a set of arbitrary orders under the same subset nonce. A subset nonce can only be cancelled manually. When a subset nonce is invalidated, all the orders sharing this subset nonce become invalid.
This system allows for innovative features such as OCO to replace passive orders (with more aggressive orders). The protocol also supports batch cancellation for orders and other "cancel-all" features.
See more details about our triple-nonce system Triple-nonce System
The LooksRare Protocol supports partial fills. The strategy contract decides whether to invalidate the order nonce. For instance, a strategy could include a stand-alone logic allowing multiple fills.
If the strategy does not invalidate the order nonce, it will instead map the order hash to the user's
orderNonce. This prevents the execution of another maker order, which may share the same order nonce.
- Each order isn't atomic anymore, meaning that a strategy can include stand-alone logic allowing multiple fills.
- Events for (
TakerAsk) reflect whether the order is invalidated.
The LooksRare Protocol implements an affiliate system. All functions for executing orders accept an affiliate address, if set, the system would give a percent of the protocol fee from the trade to the affiliate defined in the call.
The affiliate rates are defined in basis points and are managed in the
- Each “execution” function at the protocol level has an affiliate system.
- Each affiliate address has a mapping with the percentage it can obtain for referring new users.
- When a transaction occurs with a valid affiliate address specified, there is an event issued (
Batch listing in a single signature
A signature can include an arbitrarily large number of maker orders. To do so, users can sign a Merkle root from a tree that is computed using different order hashes (derived from multiple
- With the protocol, one signature can include an arbitrarily large number of maker orders.
- Users can sign a Merkle root that contains order hashes (vs. signing the order hash).
- The computation of the Merkle tree occurs at the application level (with the SDK). For more information, see LooksRare SDK v2
Users can submit
MakerAsk orders on a set of
itemIds with specific
- Bundles can be created only for a single collection address. A bundle can contain multiple
- Bundles can only be executed for EIP-2981 if all
itemIdsshare the same royalty fee structure (i.e. same creator percent and same recipient).
Multi-purchase in one transaction
The LooksRare Protocol enables the matching of multiple pairs of
Taker in a single transaction natively. The only requirement is that it must be using the same currency. This offers considerable savings in transaction gas.
The execution can either be atomic or non-atomic.
- Atomic: if one purchase fails, the whole transaction is reverted and the execution fails. No purchase occurred.
- Non-atomic: if one or more purchase fails, the transaction will not revert and the execution will be partially successful, meaning not all the
Makerwere able to be successfully matched to a
The protocol also offers benefits to users such as the human-readability of the signed message thanks to the use of EIP-712 signatures but it also supports EIP-1271 as a signature validation method for smart contracts.
Audit Report and Security Assurance
At LooksRare security is a top priority. The smart contracts have been rigorously audited by reputable third-party auditors to ensure the highest level of safety and reliability. These audits assess the contracts for potential vulnerabilities, and compliance with best practices in the blockchain industry.
We are committed to maintaining the highest security standards and to continuously improve our smart contract infrastructure responsibly. Below the audits reports for the LooksRare Protocol (v2).
Audit Report: https://github.com/spearbit/portfolio/blob/master/pdfs/LooksRare-Spearbit-Security-Review.pdf