Smart Contracts
Eesee
Eesee is one of the main contracts users will interact with to buy or sell NFTs. This contract allows users to create their own NFTs and to collect ESE or NFT tokens from completed lots. It also allows users to spend ESE tokens they earned from lots on NFTs from any other marketplace using EeseeSwap contract (Rarible & Opensea currently). Eesee supports Lazy Minting, so you can create lots without providing upfront gas. We also make use of Lazy Transfer functionality, so tokens you place on our marketplace can be collected only when someone interacts with your lot (e.g. buys a ticket).
When creating a lot, creator can set its deadline, max tickets users can buy and a price for a single ticket. When buying multiple tickets, additional bonus tickets are provided to the buyer, amount of which is calculated by the formula: The more tickets the user buys, the more bonus tickets they receive, making large ticket sales more profitable.
If enough tickets were bought, the contract waits for a random number from EeseeRandom and allows lot winner to collect their winnings and lot owner to collect ESE they earned. In case the lot has expired, lot owner can withdraw their NFTs. Then, the contract waits for a random number from EeseeRandom and allows lot winner to collect collect ESE they earned from that lot. In case random number was not received for 24 hours after the lot has ended, all users who participated in that lot can reclaim their tokens.
The winner is calculated on collection of rewards using binary search method, making it so that buying multiple tickets in a lot costs the same gas as buying a single ticket.
This contract is designed to be changeable in our system, so it will be replaced whennever a new version of Eesee comes out.
Eesee also supports making lots without providing upfront tokens by using "ESE" asset type. The winners of such lots will be able to either collect ESE tokens they earned from those lots, or to trade it for any NFT on any other NFT marketplace.
There is also a buyout system in place, allowing a single address to buy out all tickets in a lot and collect their assets immediately without waiting for EeseeRandom. This allows Eesee to act as a more traditional marketplace.
Available external write functions:
createLots - Creates new lots with provided assets and parameters. To create a lot a signer must have those assets approved for use in Eesee contract. A lot can be created on behalf of the signer by using a signature system. There is also an ability to create lazy mining lots using said system.
buyTickets - Spends ESE tokens in exchange for tickets for specified lots. Must have ESE tokens approved or have a valid ERC712 permit provided. When buying multiple tickets, additional bonus tickets are provided to the buyer, amount of which is calculated by the formula: $bonus = buyAmount^2 / (totalTickets * 4)$.
createLotsAndBuyTickets - Combines two of the functions above to allow creating lots and buying tickets in them in a single transaction. Is useful for cases in which ticket buyers create lots on behalf of asset sellers using a signature system.
receiveAssets - Is called by lot winner to collect assets from specified lots. Note that for ESE type lots, receiveTokens should be called by winner instead.
receiveTokens - There are a number of different cases this function can be called for:
By lot owner to collect ESE tokens earned from this lot.
For ESE type lot - The winner can call this function to collect ESE tokens collected by this lot.
In case a lot has expired while not collecting enough tickets - The winner selected after expire timestamp can call this function to claim ESE tokens collected by this lot. Note that if 24 hours pass after expireTimestamp without selecting a winner, a lot is canceled and all ticket buyers are able to reclaim their tokens with the reclaimTokens function.
reclaimAssets - In case a lot has expired while not collecting enough tickets, an owner can call this function to retrieve an asset from that lot. Also, in case a lot has collected enough tickets but random number was not selected in 24 hour window, an owner will also have an ability to reclaim the asset from that lot.
reclaimTokens - This function can only be called by ticket buyers if the lot has ended (by any means) and random number was not selected in 24 hour window. In such case ticket buyers can reclaim ESE tokens they paid for tickets back.
callExternal - Can call EeseeProxy's callExternal. Is intended to be used with multicall to add flexibility to Eesee.sol. For example, it can be used to claim/reclaim tokens and swap them for assets on other marketplaces, but it can do much more.
EeseeDrops
EeseeDrops allows anyone to create their own collection, which other users will be able to mint tokens in. Drop parameters are highly customizable, so creators will be able to set mint price, allow lists, phases, etc. Allow lists are expressed as Merkle Tree roots, so users will have to provide proofs to prove that they are in the allowlist. Metadatas for each NFT in a drop are distributed randomly and verifiably by VRF after reveal.
EeseePeripheryOneInch / EeseePeripheryUniswap
EeseePeripheryOneInch / EeseePeripheryUniswap allows users to buy tickets in Eesee, mint drops and EeseeDrops or do any other action in any other contract by swapping any token for another using 1inch or Uniswap DEX'es. This contract also allows us to get winners of fulfilled lots.
EeseeWinner
This contract allows us to calculate winners of lots.
EeseeSwap
EeseeSwapOneInch / EeseeSwapUniswap are helper contract that swap any token for another using 1inch or Uniswap DEX'es and trades that token for specified NFTs on external third-party exchanges using EeseeRouters
EeseePaymaster
EeseePaymaster is a paymaster contract for Gas Station Network that allows users to pay for gas in ESE tokens. It receives signed ESE's price and user's personal discount from our backend, verifies the signature and collects calculated ESE from a user making a call.
EeseeRandom
EeseeRandomChainlink / EeseeRandomGelato are contracts that request and store random numbers using VRF with decentralized automation technology. Automation is used to ensure that VRF is called regularly without interruption. The contract also uses binary search algorithm to determine random word and timestamp of the next VRF call based on timestamp provided. This is used in Eesee to get winners of lots and in EeseeNFTDrop to reveal metadatas of NFT Drop.
Technical Documentation Technical Documentation
EeseeMining
EeseeMining is a contract that distibutes ESE tokens to users depending on Merkle Roots passed to it. Users have to provide proofs that they are in fact, part of Merkle Tree to have an ability to collect their ESE tokens.
EeseeStaking
EeseeStaking is an ESE staking contract that has two staking schemes:
"Flexible Staking" allows users to deposit and withdraw their tokens anytime and earn rewards.
"Locked Staking", allows users to commit to leaving their tokens untouched for 90 days in exchange for a higher interst rate.
User's interest rate depends on their ESE volume on eesee platform, so whennever users spend ESE tokens on Eesee or EeseeDrops, they also increase their tier and APR in staking contract. This contract's core staking algorithm is based on SmartChef's (MasterChef) with a number of additions such as volume tier system and multiple staking schemes.
ESE
ESE is a ERC20 token with automatic vesting and permit mechanisms, which is used on eesee platform.
BESE
BESE is a wrapped version of ESE token which is allowed to be spent only on function in approvedFunctions list. The list is updated by ADMIN_ROLE from EeseeAccessManager. To prevent any possible abuse by eesee team, whenever any function is removed from approvedContracts list, all BESE holders gain the ability to unwrap all their tokens at the time of function removal back to ESE.
EeseeRouters
EeseeRouters is a general name for a number of smart contracts that buy NFTs from external third-party marketplaces. They are used in conjunction with EeseeSwap to allow users to buy NFTs for ESE tokens.
Technical Documentation for EeseeOpenseaRouter
Technical Documentation for EeseeRaribleRouter
EeseeMinter
EeseeMinter is a helper contract that deploys and/or mints new NFT. It allows us to lazy mint new NFTs and create drops collections. It utilizes OpenZeppelin's Clones library to save deployment gas.
EeseeFeeSplitter
EeseeFeeSplitter is an contract that is used to split fees between multiple destinations, such as EeseeStaking, EeseeMining, DAO and Team's treasury.
EeseeProxy
EeseeProxy allows Eesee to call any contract in another context. This feature can be used together with multicall to call arbitrary external contracts.
EeseeOnRamp / EeseeOffRamp
Because vesting for ESE token is happening on chain other than staking & mining, we incorporated EeseeOnRamp together with EeseeOffRamp contracts to our architecture to have a way of transfering those vested tokens to staking and mining contracts. forward(bytes memory data) function in EeseeOnRampProxy is expected to be called regularly either from our backend, or by our community members.
Technical Documentation Technical Documentation Technical Documentation Technical Documentation Technical Documentation Technical Documentation
EeseeOffchain
EeseeOffchain is a centralized alternative to Eesee.sol, that allows Eesee team to create lots with arbitrary logic. For example, having a ticket giveaway for participating in off-chain activities. To do all actions in EeseeOffchain, users must receive a signature from SIGNER_ROLE that confirms their intent and that the data they provided for their actions is valid. Using EeseeOffchain, users are able to all the same actions they could with Eesee:
Create lots with digital assets of your choosing.
Buy tickets in lots to have a chance of winning digital assets
Collect winnings and ESE tokens from finished lots.
All those actions emit events that are indexed by our backend, which executes all logic, like calculating ticket amounts or selecting a winner.
Last updated