crowetic/protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update protocol docs (#421)

Browse Source 
* Update protocol docs

* Added functions

* fix table

* eligbility section?

* Trader.xyz shoutout

* Up to
This commit is contained in:
Jacob Evans
2022-02-11 22:53:49 +10:00
committed by GitHub
parent e084807a8f
commit f6edbd210c
11 changed files with 978 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

527
docs/basics/functions.rst
View File

@@ -67,6 +67,46 @@ Below is a catalog of basic Exchange functionality. For more advanced usage, lik
| `transferProtocolFeesForPools`_ | Transfers protocol fees from escrow to the 0x Staking System. |
| | This should be called near the end of each epoch. |
+-----------------------------------------+--------------------------------------------------------------------------+
| **NFT Orders** | **Overview** |
+-----------------------------------------+--------------------------------------------------------------------------+
| `sellERC721`_ | These are specialised orders for NFT trading |
+-----------------------------------------+ |
| `buyERC721`_ | |
+-----------------------------------------+ |
| `batchBuyERC721s`_ | |
+-----------------------------------------+ |
| `matchERC721Orders`_ | |
+-----------------------------------------+ |
| `batchMatchERC721Orders`_ | |
+-----------------------------------------+ |
| `preSignERC721Order`_ | |
+-----------------------------------------+ |
| `validateERC721OrderSignature`_ | |
+-----------------------------------------+ |
| `validateERC721OrderProperties`_ | |
+-----------------------------------------+ |
| `getERC721OrderStatus`_ | |
+-----------------------------------------+ |
| `getERC721OrderHash`_ | |
+-----------------------------------------+ +
| `sellERC1155`_ | |
+-----------------------------------------+ +
| `buyERC1155`_ | |
+-----------------------------------------+ +
| `batchCancelERC1155Orders`_ | |
+-----------------------------------------+ +
| `batchBuyERC1155s`_ | |
+-----------------------------------------+ +
| `preSignERC1155Order`_ | |
+-----------------------------------------+ +
| `validateERC1155OrderSignature`_ | |
+-----------------------------------------+ +
| `validateERC1155OrderProperties`_ | |
+-----------------------------------------+ +
| `getERC1155OrderInfo`_ | |
+-----------------------------------------+ +
| `getERC1155OrderHash`_ | |
+-----------------------------------------+--------------------------------------------------------------------------+
Limit Orders
@@ -733,3 +773,490 @@ This function transfers protocol fees from `Fee Collectors <../architecture/fee_
/// @param poolIds Staking pool IDs
function transferProtocolFeesForPools(bytes32[] calldata poolIds)
external;
NFT Orders
==========
sellERC721
----------------------------
This function sells an ERC721 token given a buy order.
.. code-block:: solidity
/// @dev Sells an ERC721 asset to fill the given order.
/// @param buyOrder The ERC721 buy order.
/// @param signature The order signature from the maker.
/// @param 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.
/// @param 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.
/// @param 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.
function sellERC721(
LibNFTOrder.ERC721Order _calldata_ buyOrder,
LibSignature.Signature _calldata_ signature,
uint256 erc721TokenId,
bool unwrapNativeToken,
bytes _calldata_ callbackData
)
_external_;
buyERC721
----------------------------
This function buys an ERC721 token given a sell order.
.. code-block:: solidity
/// @dev Buys an ERC721 asset by filling the given order.
/// @param sellOrder The ERC721 sell order.
/// @param signature The order signature.
/// @param callbackData If this parameter is non-zero, invokes
/// `zeroExERC721OrderCallback` on `msg.sender` after
/// the ERC721 asset has been transferred to `msg.sender`
/// but before transferring the ERC20 tokens to the seller.
/// Native tokens acquired during the callback can be used
/// to fill the order.
function buyERC721(
LibNFTOrder.ERC721Order _calldata_ sellOrder,
LibSignature.Signature _calldata_ signature,
bytes _calldata_ callbackData
)
_external_
_payable_;
cancelERC721Order
----------------------------
This function cancels an ERC721 order using the order `nonce` field.
.. code-block:: solidity
/// @dev Cancel a single ERC721 order by its nonce. The caller
/// should be the maker of the order. Silently succeeds if
/// an order with the same nonce has already been filled or
/// cancelled.
/// @param orderNonce The order nonce.
function cancelERC721Order(uint256 orderNonce)
_external_;
batchCancelERC721Orders
----------------------------
This function cancels an number of ERC721 order using the order `nonce` field.
.. code-block:: solidity
/// @dev Cancel multiple ERC721 orders by their nonces. The caller
/// should be the maker of the orders. Silently succeeds if
/// an order with the same nonce has already been filled or
/// cancelled.
/// @param orderNonces The order nonces.
function batchCancelERC721Orders(uint256[] _calldata_ orderNonces)
_external_;
batchBuyERC721s
----------------------------
This function buys a number of ERC721's. If you wish the transaction to revert unless ALL NFT's are purchased, set `revertIfIncomplete` to true.
.. code-block:: solidity
/// @dev Buys multiple ERC721 assets by filling the
/// given orders.
/// @param sellOrders The ERC721 sell orders.
/// @param signatures The order signatures.
/// @param revertIfIncomplete If true, reverts if this
/// function fails to fill any individual order.
/// @return successes An array of booleans corresponding to whether
/// each order in `orders` was successfully filled.
function batchBuyERC721s(
LibNFTOrder.ERC721Order[] _calldata_ sellOrders,
LibSignature.Signature[] _calldata_ signatures,
bool revertIfIncomplete
)
_external_
_payable_
returns (bool[] _memory_ successes);
matchERC721Orders
----------------------------
This function matches a buy order and a sell order together. The matcher receives any spread in price.
.. code-block:: solidity
/// @dev Matches a pair of complementary orders that have
/// a non-negative spread. Each order is filled at
/// their respective price, and the matcher receives
/// a profit denominated in the ERC20 token.
/// @param sellOrder Order selling an ERC721 asset.
/// @param buyOrder Order buying an ERC721 asset.
/// @param sellOrderSignature Signature for the sell order.
/// @param buyOrderSignature Signature for the buy order.
/// @return profit The amount of profit earned by the caller
/// of this function (denominated in the ERC20 token
/// of the matched orders).
function matchERC721Orders(
LibNFTOrder.ERC721Order _calldata_ sellOrder,
LibNFTOrder.ERC721Order _calldata_ buyOrder,
LibSignature.Signature _calldata_ sellOrderSignature,
LibSignature.Signature _calldata_ buyOrderSignature
)
_external_
returns (uint256 profit);
batchMatchERC721Orders
----------------------------
This function matches a buy orders and a sell orders together. The matcher receives any spread in price.
.. code-block:: solidity
/// @dev Matches pairs of complementary orders that have
/// non-negative spreads. Each order is filled at
/// their respective price, and the matcher receives
/// a profit denominated in the ERC20 token.
/// @param sellOrders Orders selling ERC721 assets.
/// @param buyOrders Orders buying ERC721 assets.
/// @param sellOrderSignatures Signatures for the sell orders.
/// @param buyOrderSignatures Signatures for the buy orders.
/// @return profits The amount of profit earned by the caller
/// of this function for each pair of matched orders
/// (denominated in the ERC20 token of the order pair).
/// @return successes An array of booleans corresponding to
/// whether each pair of orders was successfully matched.
function batchMatchERC721Orders(
LibNFTOrder.ERC721Order[] _calldata_ sellOrders,
LibNFTOrder.ERC721Order[] _calldata_ buyOrders,
LibSignature.Signature[] _calldata_ sellOrderSignatures,
LibSignature.Signature[] _calldata_ buyOrderSignatures
)
_external_
returns (uint256[] _memory_ profits, bool[] _memory_ successes);
preSignERC721Order
----------------------------
This function pre-signs an order. Useful for contracts that wish to buy or sell an NFT.
.. code-block:: solidity
/// @dev Approves an ERC721 order on-chain. After pre-signing
/// the order, the `PRESIGNED` signature type will become
/// valid for that order and signer.
/// @param order An ERC721 order.
function preSignERC721Order(LibNFTOrder.ERC721Order _calldata_ order)
_external_;
validateERC721OrderSignature
----------------------------
A read function to validate an ERC721 order signature.
.. code-block:: solidity
/// @dev Checks whether the given signature is valid for the
/// the given ERC721 order. Reverts if not.
/// @param order The ERC721 order.
/// @param signature The signature to validate.
function validateERC721OrderSignature(
LibNFTOrder.ERC721Order _calldata_ order,
LibSignature.Signature _calldata_ signature
)
_external_
_view_;
validateERC721OrderProperties
---------------------------------
A read function to validate a property based order with a particular token id.
.. code-block:: solidity
/// @dev If the given order is buying an ERC721 asset, checks
/// whether or not the given token ID satisfies the required
/// properties specified in the order. If the order does not
/// specify any properties, this function instead checks
/// whether the given token ID matches the ID in the order.
/// Reverts if any checks fail, or if the order is selling
/// an ERC721 asset.
/// @param order The ERC721 order.
/// @param erc721TokenId The ID of the ERC721 asset.
function validateERC721OrderProperties(
LibNFTOrder.ERC721Order _calldata_ order,
uint256 erc721TokenId
)
_external_
_view_;
getERC721OrderStatus
----------------------------
A read function to return the order status. E.g whether it is filled, cancelled or expired.
.. code-block:: solidity
/// @dev Get the current status of an ERC721 order.
/// @param order The ERC721 order.
/// @return status The status of the order.
function getERC721OrderStatus(LibNFTOrder.ERC721Order _calldata_ order)
_external_
_view_
returns (LibNFTOrder.OrderStatus status);
getERC721OrderHash
----------------------------
A read function to return the uniquie order hash.
.. code-block:: solidity
/// @dev Get the canonical hash of an ERC721 order.
/// @param order The ERC721 order.
/// @return orderHash The order hash.
function getERC721OrderHash(LibNFTOrder.ERC721Order _calldata_ order)
_external_
_view_
returns (bytes32 orderHash);
getERC721OrderStatusBitVector
---------------------------------
.. code-block:: solidity
/// @dev Get the order status bit vector for the given
/// maker address and nonce range.
/// @param maker The maker of the order.
/// @param nonceRange Order status bit vectors are indexed
/// by maker address and the upper 248 bits of the
/// order nonce. We define `nonceRange` to be these
/// 248 bits.
/// @return bitVector The order status bit vector for the
/// given maker and nonce range.
function getERC721OrderStatusBitVector(address maker, uint248 nonceRange)
_external_
_view_
returns (uint256 bitVector);
sellERC1155
----------------------------
Sells an ERC115 token given a buy order.
.. code-block:: solidity
/// @dev Sells an ERC1155 asset to fill the given order.
/// @param buyOrder The ERC1155 buy order.
/// @param signature The order signature from the maker.
/// @param erc1155TokenId The ID of the ERC1155 asset being
/// sold. If the given order specifies properties,
/// the asset must satisfy those properties. Otherwise,
/// it must equal the tokenId in the order.
/// @param erc1155SellAmount The amount of the ERC1155 asset
/// to sell.
/// @param 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.
/// @param callbackData If this parameter is non-zero, invokes
/// `zeroExERC1155OrderCallback` on `msg.sender` after
/// the ERC20 tokens have been transferred to `msg.sender`
/// but before transferring the ERC1155 asset to the buyer.
function sellERC1155(
LibNFTOrder.ERC1155Order _calldata_ buyOrder,
LibSignature.Signature _calldata_ signature,
uint256 erc1155TokenId,
uint128 erc1155SellAmount,
bool unwrapNativeToken,
bytes _calldata_ callbackData
)
_external_;
buyERC1155
----------------------------
Buys an ERC115 token given a sell order.
.. code-block:: solidity
/// @dev Buys an ERC1155 asset by filling the given order.
/// @param sellOrder The ERC1155 sell order.
/// @param signature The order signature.
/// @param erc1155BuyAmount The amount of the ERC1155 asset
/// to buy.
/// @param callbackData If this parameter is non-zero, invokes
/// `zeroExERC1155OrderCallback` on `msg.sender` after
/// the ERC1155 asset has been transferred to `msg.sender`
/// but before transferring the ERC20 tokens to the seller.
/// Native tokens acquired during the callback can be used
/// to fill the order.
function buyERC1155(
LibNFTOrder.ERC1155Order _calldata_ sellOrder,
LibSignature.Signature _calldata_ signature,
uint128 erc1155BuyAmount,
bytes _calldata_ callbackData
)
_external_
_payable_;
cancelERC1155Order
----------------------------
Cancels an ERC115 order given the order struct.
.. code-block:: solidity
/// @dev Cancel a single ERC1155 order. The caller should be the
/// maker of the order. Silently succeeds if the order has
/// already been filled or cancelled.
/// @param order The order to cancel.
function cancelERC1155Order(LibNFTOrder.ERC1155Order _calldata_ order)
_external_;
batchCancelERC1155Orders
----------------------------
Cancels a number of ERC115 orders.
.. code-block:: solidity
/// @dev Cancel multiple ERC1155 orders. The caller should be the
/// maker of the orders. Silently succeeds if an order has
/// already been filled or cancelled.
/// @param orders The orders to cancel.
function batchCancelERC1155Orders(LibNFTOrder.ERC1155Order[] _calldata_ orders)
_external_;
batchBuyERC1155s
----------------------------
Buys multiple ERC1155 assets given the sell orders.
.. code-block:: solidity
/// @dev Buys multiple ERC1155 assets by filling the
/// given orders.
/// @param sellOrders The ERC1155 sell orders.
/// @param signatures The order signatures.
/// @param erc1155TokenAmounts The amounts of the ERC1155 assets
/// to buy for each order.
/// @param revertIfIncomplete If true, reverts if this
/// function fails to fill any individual order.
/// @return successes An array of booleans corresponding to whether
/// each order in `orders` was successfully filled.
function batchBuyERC1155s(
LibNFTOrder.ERC1155Order[] _calldata_ sellOrders,
LibSignature.Signature[] _calldata_ signatures,
uint128[] _calldata_ erc1155TokenAmounts,
bool revertIfIncomplete
)
_external_
_payable_
returns (bool[] _memory_ successes);
preSignERC1155Order
----------------------------
Pre-signs the order on-chain. This is useful for smart contracts.
.. code-block:: solidity
/// @dev Approves an ERC1155 order on-chain. After pre-signing
/// the order, the `PRESIGNED` signature type will become
/// valid for that order and signer.
/// @param order An ERC1155 order.
function preSignERC1155Order(LibNFTOrder.ERC1155Order _calldata_ order)
_external_;
validateERC1155OrderSignature
---------------------------------
A read function to validate the ERC1155 order signatures.
.. code-block:: solidity
/// @dev Checks whether the given signature is valid for the
/// the given ERC1155 order. Reverts if not.
/// @param order The ERC1155 order.
/// @param signature The signature to validate.
function validateERC1155OrderSignature(
LibNFTOrder.ERC1155Order calldata order,
LibSignature.Signature calldata signature
)
external
view;
validateERC1155OrderProperties
---------------------------------
A read function to validate the specific ERC1155 asset against a property based order.
.. code-block:: solidity
/// @dev If the given order is buying an ERC1155 asset, checks
/// whether or not the given token ID satisfies the required
/// properties specified in the order. If the order does not
/// specify any properties, this function instead checks
/// whether the given token ID matches the ID in the order.
/// Reverts if any checks fail, or if the order is selling
/// an ERC1155 asset.
/// @param order The ERC1155 order.
/// @param erc1155TokenId The ID of the ERC1155 asset.
function validateERC1155OrderProperties(
LibNFTOrder.ERC1155Order calldata order,
uint256 erc1155TokenId
)
external
view;
getERC1155OrderInfo
----------------------------
A read function to get the ERC1155 order info. Such as whether it has been cancelled, expired or filled.
.. code-block:: solidity
/// @dev Get the order info for an ERC1155 order.
/// @param order The ERC1155 order.
/// @return orderInfo Infor about the order.
function getERC1155OrderInfo(LibNFTOrder.ERC1155Order calldata order)
external
view
returns (LibNFTOrder.OrderInfo memory orderInfo);
getERC1155OrderHash
----------------------------
A read function to calculate the unique order hash.
.. code-block:: solidity
/// @dev Get the canonical hash of an ERC1155 order.
/// @param order The ERC1155 order.
/// @return orderHash The order hash.
function getERC1155OrderHash(LibNFTOrder.ERC1155Order calldata order)
external
view
returns (bytes32 orderHash);