Order types

Element NFT market is built on off-chain order book and on-chain matching system. off-chain order with EIP-712 signatures are called Maker Orders. The paramters against a maker order are called Taker Param.

A maker order is stored at off-chain order book (a special order service for query and storage orders), maker order is passive, it can only be executed by a taker(EOA or smart contract) to execute transaction on chain, so the gas fees are paid by taker.

Maker Order

ERC721 SellOrder

A sell order means that the maker wants to sell the NFT. "Listing" action will make a sell order.

  struct NFTSellOrder {
        address maker; 
        address taker; 
        uint256 expiry;
        uint256 nonce;
        IERC20 erc20Token; 
        uint256 erc20TokenAmount;
        Fee[] fees;
        address nft;
        uint256 nftId;
    }
    
    struct Fee {
        address recipient;
        uint256 amount;
        bytes feeData;
    }
    
    struct Signature {
        SignatureType signatureType; 
        uint8 v;
        bytes32 r;
        bytes32 s;
    }

Params descriptions:

• maker - the address of the signer of this maker order

• taker - the address of the taker who can take this order if specified, or keep null

• expiry - the time when this order expired (second)

• nonce - the unique id of this order, use a auto increment id will save gas

• erc20Token - the payment token address, 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE represent native token

• erc20TokenAmount - the amount of the payment token

• fees - the fees of this order

• nft - the collection address of the NFT

• nftId - the tokenId of this collection address

• signatureType - 0 EIP721, 1 PRESIGNED

• v、r、s - Ethereum uses ECDSA signatures.

ERC721 BuyOrder

A buy order means that the maker wants to buy an NFT. "Make Offer" action will make a buy order.

 struct NFTBuyOrder {
        address maker;
        address taker;
        uint256 expiry;
        uint256 nonce;
        IERC20 erc20Token;
        uint256 erc20TokenAmount;
        Fee[] fees;
        address nft;
        uint256 nftId;
        Property[] nftProperties;
    }
    
    struct Property {
        IPropertyValidator propertyValidator;
        bytes propertyData;
    }

    struct Fee {
        address recipient;
        uint256 amount;
        bytes feeData;
    }

Params descriptions:

• maker、taker、expiry、nonce、erc20Token、erc20TokenAmount、fees、nft、nftId、signatureType、v、r、s - same as SellOrder

• nftProperties - used for collection order if push a Property.propertyValidator = address(0) to the array

ERC1155 SellOrder

  struct ERC1155SellOrder {
        address maker;
        address taker;
        uint256 expiry;
        uint256 nonce;
        IERC20 erc20Token;
        uint256 erc20TokenAmount;
        Fee[] fees;
        address erc1155Token;
        uint256 erc1155TokenId;
        // End of fields shared with NFTOrder
        uint128 erc1155TokenAmount;
    }

• maker、taker、expiry、nonce、erc20Token、erc20TokenAmount、fees 、signatureType、v、r、s- same as ERC721 SellOrder

• erc1155Token - the collection address of ERC1155, same as ER721 nft

• erc1155TokenId - the tokenId of this collection, same as ERC721 nftId

• erc1155TokenAmount - the amount of this tokenId

ERC1155 BuyOrder

   struct ERC1155BuyOrder {
        address maker;
        address taker;
        uint256 expiry;
        uint256 nonce;
        IERC20 erc20Token;
        uint256 erc20TokenAmount;
        Fee[] fees;
        address erc1155Token;
        uint256 erc1155TokenId;
        Property[] erc1155TokenProperties;
        // End of fields shared with NFTOrder
        uint128 erc1155TokenAmount;
    }

• maker、taker、expiry、nonce、erc20Token、erc20TokenAmount、fees、signatureType、v、r、s、erc1155Token、erc1155TokenId、erc1155TokenAmount - same as ERC1155 SellOrder

• erc1155TokenProperties - same as ERC721 nftProperties

Taker Param

Take param used to call smart contract functions to match against a maker order.

buyERC721

Buys an ERC721 asset by filling the given sell order.

function buyERC721(
    LibNFTOrder.NFTSellOrder memory sellOrder, 
    LibSignature.Signature memory signature
) public override payable 

• sellOrder - the sell order struct params

• signature - the signature of the sell order

buyERC721Ex

Advance version of buyERC721 with more feature: mix payment with ETH+WETH、specify taker and callback.

  function buyERC721Ex(
        LibNFTOrder.NFTSellOrder memory sellOrder,
        LibSignature.Signature memory signature,
        address taker,
        bytes memory callbackData
    ) public override payable

• sellOrder、signature - same as buyERC721

• taker - the taker of order, msg.sender or the real buyer behind a aggregator like gem.xyz/genie.xyz

• callbackData - call back function to the taker address if needed

sellERC721

Sells an ERC721 asset to fill the given order.

function sellERC721(
        LibNFTOrder.NFTBuyOrder memory buyOrder,
        LibSignature.Signature memory signature,
        uint256 erc721TokenId,
        bool unwrapNativeToken,
        bytes memory callbackData
    ) 

• buyOrder - the erc721 buy order

• signature - the signature of the buy order

• erc721TokenId - The ID of the ERC721 asset being sold. If the given order specifies properties,the asset must satisfy those properties. Otherwise, it must equal the tokenId in the order.

• unwrapNativeToken - If this parameter is true and the ERC20 token of the order is e.g. WETH, unwraps the token before transferring it to the taker.

• callbackData - callbackData If this parameter is non-zero, invokes zeroExERC721OrderCallback on msg.sender after the ERC20 tokens have been transferred to msg.sender but before transferring the ERC721 asset to the buyer.

buyERC1155

Same as buyERC721.

   function buyERC1155(
        LibNFTOrder.ERC1155SellOrder memory sellOrder,
        LibSignature.Signature memory signature,
        uint128 erc1155BuyAmount
    ) public override payable

• erc1155BuyAmount - the number want to buy

buyERC1155Ex

Advance version of buyERC1155 with more feature: mix payment with ETH+WETH、specify taker and callback.

  function buyERC1155Ex(
        LibNFTOrder.ERC1155SellOrder memory sellOrder,
        LibSignature.Signature memory signature,
        address taker,
        uint128 erc1155BuyAmount,
        bytes memory callbackData
    )

sellERC1155

same as sellERC721

   function sellERC1155(
        LibNFTOrder.ERC1155BuyOrder memory buyOrder,
        LibSignature.Signature memory signature,
        uint256 erc1155TokenId,
        uint128 erc1155SellAmount,
        bool unwrapNativeToken,
        bytes memory callbackData
    )

• erc1155SellAmount - the number want to sell