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
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 978 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/additional/bounties.rst
View File

@ -2,47 +2,15 @@
Bounties
###############################
We run an ongoing bug bounty for the 0x Protocol smart contracts! The program is open to anyone and
rewards up to **$100,000 for critical exploits**. The scope and disclosure instructions are below.
Rewards
-------
The severity of reported vulnerabilities will be graded according to the `CVSS <https://www.first.org/cvss/>`_ (Common Vulnerability Scoring Standard).
The following table will serve as a guideline for reward decisions:
The bug bounties on this page apply only to the *0x smart contracts* on Ethereum mainnet, Binance Smart Chain, Polygon, Avalanche, Fantom, Celo, Optimism and future deployments in other EVM-compatible networks announced through our official communication channels.
+----------------------------+---------------------+
| **Exploit Score** | **Reward** |
+----------------------------+---------------------+
| Critical (CVSS 9.0 - 10.0) | $10,000 - $100,000 |
+----------------------------+---------------------+
| High (CVSS 7.0 - 8.9) | $2,500 - $10,000 |
+----------------------------+---------------------+
| Medium (CVSS 4.0 - 6.9) | $1,000 - $2,500 |
+----------------------------+---------------------+
| Low (CVSS 0.0 - 3.9) | $0 - $1,000 |
+----------------------------+---------------------+
Bug reports pertaining to 0x API and 0x web interfaces (e.g. Matcha, 0x.org), both in terms of UI/UX or servers/infrastructure, are not eligible. Only the first reporter of a given contract vulnerability will be rewarded, and findings already discovered as part of a formal audit are ineligible.
Please note that any rewards will ultimately be awarded at the discretion of ZeroEx Intl. All rewards will be paid out in ZRX.
Overview
--------
Areas of Interest
-----------------
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Area** | **Examples** |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| Loss of funds | * A user loses funds in a way that they did not explicitly authorize (e.g an account is able to gain access to an ``AssetProxy`` and drain user funds). |
| | * A user authorized a transaction or trade but spends more assets than normally expected (e.g an order is allowed to be over-filled). |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| Unintended contract state | * A user is able to update the state of a contract such that it is no longer useable (e.g permanently lock a mutex). |
| | * Any assets get unexpectedly "stuck" in a contract with regular use of the contract's public methods. |
| | * An action taken in the staking contracts is applied to an incorrect epoch. |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| Bypassing time locks | * The ``ZeroExGovernor`` is allowed to bypass the timelock for transactions where it is not explicitly allowed to do so. |
| | * A user is allowed to bypass the ``ZeroExGovernor``. |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| Incorrect math | * Overflows or underflow result in unexpected behavior. |
| | * The staking reward payouts are incorrect. |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
0x has completed smart contract audits with Consensys Diligence, Trail of Bits and ABDK. We run a continuous bug bounty program for the V4 release of the 0x core contracts.
Scope
-----
@ -51,14 +19,14 @@ The following contracts are in scope of the bug bounty. Please note that any bug
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| **Release** | **Contracts** | **Commit Hash** |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| Exchange V4 | * Documentation at `https://0xprotocol.readthedocs.io/en/latest/ <https://0xprotocol.readthedocs.io/en/latest/>`__ | `72a74e7c66 <https://github.com/0xProject/protocol/tree/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src>`__ |
| | * `ZeroEx.sol <https://github.com/0xProject/protocol/blob/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/ZeroEx.sol>`__ | |
| | * `ZeroExOptimized.sol <https://github.com/0xProject/protocol/blob/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/ZeroExOptimized.sol>`__ | |
| | * `external/*.sol <https://github.com/0xProject/protocol/tree/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/external>`__ | |
| | * `features/**.sol <https://github.com/0xProject/protocol/tree/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/features>`__ | |
| | * `fixins/*.sol <https://github.com/0xProject/protocol/tree/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/fixins>`__ | |
| | * `migrations/*.sol <https://github.com/0xProject/protocol/tree/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/migrations>`__ | |
| | * `storage/*.sol <https://github.com/0xProject/protocol/tree/72a74e7c66e27da02dd9f4ce604ad057c740c304/contracts/zero-ex/contracts/src/storage>`__ | |
| Exchange V4 | * Documentation at `https://protocol.0x.org/en/latest/ <https://protocol.0x.org/en/latest/>`__ | `2cbeb9c <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src>`__ |
| | * `ZeroEx.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/ZeroEx.sol>`__ | |
| | * `ZeroExOptimized.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/ZeroExOptimized.sol>`__ | |
| | * `external/*.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/external>`__ | |
| | * `features/**.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/features>`__ | |
| | * `fixins/*.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/fixins>`__ | |
| | * `migrations/*.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/migrations>`__ | |
| | * `storage/*.sol <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src/storage>`__ | |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| Exchange V3 | * `ERC20BridgeProxy.sol <https://github.com/0xProject/0x-monorepo/blob/fb8360edfd4f42f2d2b127b95c156eb1b0daa02b/contracts/asset-proxy/contracts/src/ERC20BridgeProxy.sol>`_ (`spec <https://github.com/0xProject/0x-protocol-specification/blob/master/asset-proxy/erc20-bridge-proxy.md>`__) | `fb8360edfd <https://github.com/0xProject/0x-monorepo/tree/fb8360edfd4f42f2d2b127b95c156eb1b0daa02b/contracts>`__ |
| | * `Exchange.sol <https://github.com/0xProject/0x-monorepo/blob/fb8360edfd4f42f2d2b127b95c156eb1b0daa02b/contracts/exchange/contracts/src/Exchange.sol>`__ (`spec <https://github.com/0xProject/0x-protocol-specification/blob/master/v3/v3-specification.md>`__) | |
@ -67,7 +35,7 @@ The following contracts are in scope of the bug bounty. Please note that any bug
| | * `StakingProxy.sol <https://github.com/0xProject/0x-monorepo/blob/fb8360edfd4f42f2d2b127b95c156eb1b0daa02b/contracts/staking/contracts/src/StakingProxy.sol>`_ (`spec <https://github.com/0xProject/0x-protocol-specification/blob/master/staking/staking-specification.md>`__) | |
| | * `ZrxVault.sol <https://github.com/0xProject/0x-monorepo/blob/fb8360edfd4f42f2d2b127b95c156eb1b0daa02b/contracts/staking/contracts/src/ZrxVault.sol>`_ (`spec <https://github.com/0xProject/0x-protocol-specification/blob/master/staking/staking-specification.md>`__) | |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| Exchange V2.1 | * `src/2.0.0/protocol <https://github.com/0xProject/0x-monorepo/tree/ff70c5ecfe28eff14e1a372c5e493b8f5363e1d0/packages/contracts/src/2.0.0/protocol>`_ | `ff70c5ecfe <https://github.com/0xProject/0x-monorepo/tree/ff70c5ecfe28eff14e1a372c5e493b8f5363e1d0/contracts>`_ |
| Exchange V2.1 | * `src/2.0.0/protocol <https://github.com/0xProject/0x-monorepo/tree/ff70c5ecfe28eff14e1a372c5e493b8f5363e1d0/packages/contracts/src/2.0.0/protocol>`_ | `ff70c5ecfe <https://github.com/0xProject/0x-monorepo/tree/ff70c5ecfe28eff14e1a372c5e493b8f5363e1d0/packages/contracts/src/2.0.0>`_ |
| | * `src/2.0.0/utils <https://github.com/0xProject/0x-monorepo/tree/ff70c5ecfe28eff14e1a372c5e493b8f5363e1d0/packages/contracts/src/2.0.0/utils>`_ | |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| MultiAssetProxy | * `MultiAssetProxy.sol <https://github.com/0xProject/0x-monorepo/blob/c4d9ef9f83508154fe9db35796b6b86aeb0f2240/contracts/asset-proxy/contracts/src/MultiAssetProxy.sol>`_ | `c4d9ef9f83 <https://github.com/0xProject/0x-monorepo/tree/c4d9ef9f83508154fe9db35796b6b86aeb0f2240/contracts>`_ |
@ -78,9 +46,37 @@ The following contracts are in scope of the bug bounty. Please note that any bug
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ERC20BridgeProxy | * `ERC20BridgeProxy.sol <https://github.com/0xProject/0x-monorepo/blob/281658ba349a2c5088b40b503998bea5020284a6/contracts/asset-proxy/contracts/src/ERC20BridgeProxy.sol>`__ | `281658ba34 <https://github.com/0xProject/0x-monorepo/tree/281658ba349a2c5088b40b503998bea5020284a6/contracts>`_ |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
| ExchangeProxy | * `contracts/src <https://github.com/0xProject/0x-monorepo/tree/7967a8416c76e34ff5a0a4eb80e7b33ff8c0e297/contracts/zero-ex>`__ | `7967a8416c <https://github.com/0xProject/0x-monorepo/tree/7967a8416c76e34ff5a0a4eb80e7b33ff8c0e297/contracts>`_ |
| ExchangeProxy | * `contracts/src <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src>`__ | `2cbeb9c <https://github.com/0xProject/protocol/tree/audit/nft-orders-address-findings/contracts/zero-ex/contracts/src>`_ |
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
Bounties
--------
The bounty program will pay out rewards according to the severity of a vulnerability. The severity of reported vulnerabilities will be graded according to the `CVSS <https://www.first.org/cvss/>`__ (Common Vulnerability Scoring Standard).
The final reward amount is at the sole discretion of 0x Labs and will be paid in the specified sum in either USD or ETH.
+----------------------------+---------------------+
| **Exploit Score** | **Reward** |
+----------------------------+---------------------+
| Critical (CVSS 9.0 - 10.0) | up to $1,000,000 |
+----------------------------+---------------------+
| High (CVSS 7.0 - 8.9) | up to $350,000 |
+----------------------------+---------------------+
| Medium (CVSS 4.0 - 6.9) | up to $35,000 |
+----------------------------+---------------------+
| Low (CVSS 0.0 - 3.9) | up to $5,000 |
+----------------------------+---------------------+
Recent Inclusions
-----------------
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Change** | **** |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| NFT feature | * Trade ERC721 and ERC1155 assets. See `ZEIP-93 <https://github.com/0xProject/ZEIPs/issues/93>`__ for more details |
+---------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
Disclosures
-----------
Please e-mail all submissions to security@0x.org with the subject "BUG BOUNTY". Your submission

7
docs/additional/exceptional_erc20s.rst
View File

@ -17,3 +17,10 @@ Known tokens:
- LINK
- sUSD
- USDT
Tokens with Fees on Transfer
----------------------------
These tokens do not follow the ERC20 specification. As such the protocol expects the transfer to transfer
the specified amount, or revert. Since tokens with transfer fees do not meet this criteria, the behaviour
of the protocol with these tokens is unspecified. In most cases it will result in an overall transaction failure
due to various slippage protections.

21
docs/additional/releases.rst
View File

@ -17,10 +17,12 @@ This page outlines upcoming releases and expected changes.
+---------------------------------------------+---------------------------------------------------------------+----------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| **Name** | **Overview** | **Est Release Date** | **Status** | **Additional** |
+---------------------------------------------+---------------------------------------------------------------+----------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| `Amaretto`_ | Protocol 4.1: Efficiency + Batch Fills | 03/15/21 | Development | |
| `Nifty`_ | ERC721 and ERC1155 support | 02/14/22 | Vote | |
+---------------------------------------------+---------------------------------------------------------------+----------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| *The following releases have been deployed* | | | | |
+---------------------------------------------+---------------------------------------------------------------+----------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| `Amaretto`_ | Protocol 4.1: Efficiency + Batch Fills | 03/15/21 | Deployed | |
+---------------------------------------------+---------------------------------------------------------------+----------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| `Babooshka`_ | Connect Exchange Proxy to Staking | 02/08/21 | Deployed | `Release Notes <https://github.com/0xProject/0x-migrations/blob/main/src/exchange-proxy/migrations/log/9_babooshka.md>`__ |
+---------------------------------------------+---------------------------------------------------------------+----------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------+
| `Squire`_ | Aggregation for `V4 Orders <../basics/orders.html>`_ | 02/04/21 | Deployed | N/A |
@ -45,6 +47,19 @@ This page outlines upcoming releases and expected changes.
Upcoming
========
Nifty
--------
- ERC721 and ERC1155 order types
- Batch fills for NFT orders
- Property based orders
- Ability to receive ETH in NFT orders
Past
=====
Amaretto
--------
@ -53,10 +68,6 @@ Amaretto
- Mooniswap VIP
- Curve / Swerve VIP (via PLP Sandbox)
Past
=====
Babooshka
----------

12
docs/advanced/erc20_transformations.rst
View File

@ -57,18 +57,22 @@ Liquidity Aggregation
Liquidity can be pulled from other Decentralized Exchanges (DEX) to supplement native liquidity (0x orders). This is currently used by 0x API to provide the aggregate the best prices across the entire DEX Ecosystem. Check out `https://matcha.xyz <https://matcha.xyz>`_ to see this in action!
Supported DEX's:
Below are just a few of the Supported DEX's on Ethereum:
* Balancer
* Balancer v1/v2
* Bancor v1/v2
* Curve
* DoDo
* Dodo v1/v2
* Kyber
* MakerPSM
* MStable
* Mooniswap
* Oasis
* Shell
* Sushiswap
* Uniswap v1/v2
* Shibaswap
* Smoothy
* Uniswap v1/v2/v3
This transformation is implemented by the `FillQuoteTransformer <../architecture/transformers.html>`_. Abi-Encode the following struct to get the ``data``:

49
docs/basics/addresses.rst
View File

@ -6,16 +6,17 @@ Addresses
.. note::
This page is auto-generated. See the `contract-addresses <https://github.com/0xProject/protocol/blob/development/packages/contract-addresses/addresses.json>`_ package for an exhaustive list of contracts across all networks.
The Exchange Proxy may have different addresses on various networks, see the `Exchange Proxy Addresses <./addresses.html#exchange-proxy-addresses>`__ table for an exhaustive list.
Exchange V4
===================
.. csv-table::
exchangeProxy, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://etherscan.io/address//0xdef1c0ded9bec7f1a1670819833240f027b25eff>`_
exchangeProxyAllowanceTarget, `0xf740b67da229f2f10bcbd38a7979992fcc71b8eb <https://etherscan.io/address//0xf740b67da229f2f10bcbd38a7979992fcc71b8eb>`_
exchangeProxyFlashWallet, `0x22f9dcf4647084d6c31b2765f6910cd85c178c18 <https://etherscan.io/address//0x22f9dcf4647084d6c31b2765f6910cd85c178c18>`_
exchangeProxyGovernor, `0x618f9c67ce7bf1a50afa1e7e0238422601b0ff6e <https://etherscan.io/address//0x618f9c67ce7bf1a50afa1e7e0238422601b0ff6e>`_
exchangeProxyLiquidityProviderSandbox, `0x407b4128e9ecad8769b2332312a9f655cb9f5f3a <https://etherscan.io/address//0x407b4128e9ecad8769b2332312a9f655cb9f5f3a>`_
exchangeProxyTransformerDeployer, `0x39dce47a67ad34344eab877eae3ef1fa2a1d50bb <https://etherscan.io/address//0x39dce47a67ad34344eab877eae3ef1fa2a1d50bb>`_
exchangeProxy, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://etherscan.io/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff>`__
exchangeProxyFlashWallet, `0x22f9dcf4647084d6c31b2765f6910cd85c178c18 <https://etherscan.io/address/0x22f9dcf4647084d6c31b2765f6910cd85c178c18>`__
exchangeProxyGovernor, `0x618f9c67ce7bf1a50afa1e7e0238422601b0ff6e <https://etherscan.io/address/0x618f9c67ce7bf1a50afa1e7e0238422601b0ff6e>`__
exchangeProxyLiquidityProviderSandbox, `0x407b4128e9ecad8769b2332312a9f655cb9f5f3a <https://etherscan.io/address/0x407b4128e9ecad8769b2332312a9f655cb9f5f3a>`__
exchangeProxyTransformerDeployer, `0x39dce47a67ad34344eab877eae3ef1fa2a1d50bb <https://etherscan.io/address/0x39dce47a67ad34344eab877eae3ef1fa2a1d50bb>`__
@ -23,10 +24,11 @@ Transformers
===================
.. csv-table::
wethTransformer, `0xb2bc06a4efb20fc6553a69dbfa49b7be938034a7 <https://etherscan.io/address//0xb2bc06a4efb20fc6553a69dbfa49b7be938034a7>`_
payTakerTransformer, `0x4638a7ebe75b911b995d0ec73a81e4f85f41f24e <https://etherscan.io/address//0x4638a7ebe75b911b995d0ec73a81e4f85f41f24e>`_
fillQuoteTransformer, `0x5ce5174d7442061135ea849970ffc7763920e0fd <https://etherscan.io/address//0x5ce5174d7442061135ea849970ffc7763920e0fd>`_
affiliateFeeTransformer, `0xda6d9fc5998f550a094585cf9171f0e8ee3ac59f <https://etherscan.io/address//0xda6d9fc5998f550a094585cf9171f0e8ee3ac59f>`_
wethTransformer, `0xb2bc06a4efb20fc6553a69dbfa49b7be938034a7 <https://etherscan.io/address/0xb2bc06a4efb20fc6553a69dbfa49b7be938034a7>`__
payTakerTransformer, `0x4638a7ebe75b911b995d0ec73a81e4f85f41f24e <https://etherscan.io/address/0x4638a7ebe75b911b995d0ec73a81e4f85f41f24e>`__
affiliateFeeTransformer, `0xda6d9fc5998f550a094585cf9171f0e8ee3ac59f <https://etherscan.io/address/0xda6d9fc5998f550a094585cf9171f0e8ee3ac59f>`__
fillQuoteTransformer, `0xb4fa284689c9784a60d840eb136bb16c5246191f <https://etherscan.io/address/0xb4fa284689c9784a60d840eb136bb16c5246191f>`__
positiveSlippageFeeTransformer, `0xa9416ce1dbde8d331210c07b5c253d94ee4cc3fd <https://etherscan.io/address/0xa9416ce1dbde8d331210c07b5c253d94ee4cc3fd>`__
@ -34,10 +36,10 @@ ZRX / Staking
===================
.. csv-table::
staking, `0x2a17c35ff147b32f13f19f2e311446eeb02503f3 <https://etherscan.io/address//0x2a17c35ff147b32f13f19f2e311446eeb02503f3>`_
stakingProxy, `0xa26e80e7dea86279c6d778d702cc413e6cffa777 <https://etherscan.io/address//0xa26e80e7dea86279c6d778d702cc413e6cffa777>`_
zrxToken, `0xe41d2489571d322189246dafa5ebde1f4699f498 <https://etherscan.io/address//0xe41d2489571d322189246dafa5ebde1f4699f498>`_
zrxVault, `0xba7f8b5fb1b19c1211c5d49550fcd149177a5eaf <https://etherscan.io/address//0xba7f8b5fb1b19c1211c5d49550fcd149177a5eaf>`_
staking, `0x2a17c35ff147b32f13f19f2e311446eeb02503f3 <https://etherscan.io/address/0x2a17c35ff147b32f13f19f2e311446eeb02503f3>`__
stakingProxy, `0xa26e80e7dea86279c6d778d702cc413e6cffa777 <https://etherscan.io/address/0xa26e80e7dea86279c6d778d702cc413e6cffa777>`__
zrxToken, `0xe41d2489571d322189246dafa5ebde1f4699f498 <https://etherscan.io/address/0xe41d2489571d322189246dafa5ebde1f4699f498>`__
zrxVault, `0xba7f8b5fb1b19c1211c5d49550fcd149177a5eaf <https://etherscan.io/address/0xba7f8b5fb1b19c1211c5d49550fcd149177a5eaf>`__
@ -45,9 +47,22 @@ Miscellaneous
===================
.. csv-table::
devUtils, `0x74134cf88b21383713e096a5ecf59e297dc7f547 <https://etherscan.io/address//0x74134cf88b21383713e096a5ecf59e297dc7f547>`_
etherToken, `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 <https://etherscan.io/address//0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2>`_
erc20BridgeSampler, `0xd8c38704c9937ea3312de29f824b4ad3450a5e61 <https://etherscan.io/address//0xd8c38704c9937ea3312de29f824b4ad3450a5e61>`_
devUtils, `0x74134cf88b21383713e096a5ecf59e297dc7f547 <https://etherscan.io/address/0x74134cf88b21383713e096a5ecf59e297dc7f547>`__
etherToken, `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 <https://etherscan.io/address/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2>`__
erc20BridgeSampler, `0xd8c38704c9937ea3312de29f824b4ad3450a5e61 <https://etherscan.io/address/0xd8c38704c9937ea3312de29f824b4ad3450a5e61>`__
Exchange Proxy Addresses
=========================
Note: Some addresses have changed across various networks
.. csv-table::
Ethereum, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://etherscan.io/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff>`__
Optimism, `0xdef1abe32c034e558cdd535791643c58a13acc10 <https://optimistic.etherscan.io/address/0xdef1abe32c034e558cdd535791643c58a13acc10>`__
Binance Smart Chain, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://bscscan.com/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff>`__
Polygon, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://polygonscan.com/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff>`__
Avalanche, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://snowtrace.io/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff>`__
Fantom, `0xdef189deaef76e379df891899eb5a00a94cbc250 <https://ftmscan.com/address/0xdef189deaef76e379df891899eb5a00a94cbc250>`__
Celo, `0xdef1c0ded9bec7f1a1670819833240f027b25eff <https://explorer.celo.org/address/0xdef1c0ded9bec7f1a1670819833240f027b25eff>`__

4
docs/basics/allowances.rst
View File

@ -2,6 +2,4 @@
Allowances
###############################
Both maker and taker allowance should be be set directly on the `Exchange Proxy contract <./addresses.html#exchange-v4>`_.
For takers, legacy allowances set on the `Allowance Target <./addresses.html#exchange-v4>`_ will continue to work during this transition period but will suffer a gas penalty. It's highly encouraged to migrate allowances over to the Exchange Proxy as soon as possible to avoid interruption.
Both maker and taker allowance should be be set directly on the `Exchange Proxy contract <./addresses.html#exchange-proxy-addresses>`_.

149
docs/basics/events.rst
View File

@ -61,6 +61,18 @@ illustrates how events are emitted when trading through the Exchange Proxy.
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `TransformerMetadata`_ | A general, customizable event emitted that can be emitted by transformers as-needed. | FlashWallet |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `ERC1155OrderFilled`_ | Emitted when a `V4 ERC1155 Order <./orders.html#erc1155-orders>`_ is filled. | ExchangeProxy |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `ERC721OrderFilled`_ | Emitted when a `V4 ERC721 Order <./orders.html#erc721-orders>`_ is filled. | ExchangeProxy |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `ERC1155OrderCancelled`_ | Emitted when a `V4 ERC1155 Order <./orders.html#erc1155-orders>`_ is cancelled. | ExchangeProxy |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `ERC721OrderCancelled`_ | Emitted when a `V4 ERC721 Order <./orders.html#erc721-orders>`_ is cancelled. | ExchangeProxy |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `ERC1155OrderPreSigned`_ | Emitted when a `V4 ERC1155 Order <./orders.html#erc1155-orders>`_ is signed on-chain. | ExchangeProxy |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
| `ERC721OrderPreSigned`_ | Emitted when a `V4 ERC721 Order <./orders.html#erc721-orders>`_ is signed on-chain. | ExchangeProxy |
+-------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+
Deployed
@ -374,6 +386,143 @@ TransformerMetadata
);
ERC721OrderFilled
-------------------
.. code-block:: solidity
/// @dev Emitted whenever an `ERC721Order` is filled.
/// @param direction Whether the order is selling or
/// buying the ERC721 token.
/// @param maker The maker of the order.
/// @param taker The taker of the order.
/// @param nonce The unique maker nonce in the order.
/// @param erc20Token The address of the ERC20 token.
/// @param erc20TokenAmount The amount of ERC20 token
/// to sell or buy.
/// @param erc721Token The address of the ERC721 token.
/// @param erc721TokenId The ID of the ERC721 asset.
/// @param matcher If this order was matched with another using `matchERC721Orders()`,
/// this will be the address of the caller. If not, this will be `address(0)`.
event ERC721OrderFilled(
LibNFTOrder.TradeDirection direction,
address maker,
address taker,
uint256 nonce,
IERC20TokenV06 erc20Token,
uint256 erc20TokenAmount,
IERC721Token erc721Token,
uint256 erc721TokenId,
address matcher
);
ERC721OrderCancelled
---------------------
.. code-block:: solidity
/// @dev Emitted whenever an `ERC721Order` is cancelled.
/// @param maker The maker of the order.
/// @param nonce The nonce of the order that was cancelled.
event ERC721OrderCancelled(
address maker,
uint256 nonce
);
ERC721OrderPreSigned
---------------------
.. code-block:: solidity
/// @dev Emitted when an `ERC721Order` is pre-signed.
/// Contains all the fields of the order.
event ERC721OrderPreSigned(
LibNFTOrder.TradeDirection direction,
address maker,
address taker,
uint256 expiry,
uint256 nonce,
IERC20TokenV06 erc20Token,
uint256 erc20TokenAmount,
LibNFTOrder.Fee[] fees,
IERC721Token erc721Token,
uint256 erc721TokenId,
LibNFTOrder.Property[] erc721TokenProperties
);
ERC1155OrderFilled
-------------------
.. code-block:: solidity
/// @dev Emitted whenever an `ERC1155Order` is filled.
/// @param direction Whether the order is selling or
/// buying the ERC1155 token.
/// @param maker The maker of the order.
/// @param taker The taker of the order.
/// @param nonce The unique maker nonce in the order.
/// @param erc20Token The address of the ERC20 token.
/// @param erc20FillAmount The amount of ERC20 token filled.
/// @param erc1155Token The address of the ERC1155 token.
/// @param erc1155TokenId The ID of the ERC1155 asset.
/// @param erc1155FillAmount The amount of ERC1155 asset filled.
/// @param matcher Currently unused.
event ERC1155OrderFilled(
LibNFTOrder.TradeDirection direction,
address maker,
address taker,
uint256 nonce,
IERC20TokenV06 erc20Token,
uint256 erc20FillAmount,
IERC1155Token erc1155Token,
uint256 erc1155TokenId,
uint128 erc1155FillAmount,
address matcher
);
ERC1155OrderCancelled
---------------------
.. code-block:: solidity
/// @dev Emitted whenever an `ERC1155Order` is cancelled.
/// @param orderHash The hash the order.
/// @param maker The maker of the order.
event ERC1155OrderCancelled(
bytes32 orderHash,
address maker
);
ERC1155OrderPreSigned
---------------------
.. code-block:: solidity
/// @dev Emitted when an `ERC1155Order` is pre-signed.
/// Contains all the fields of the order.
event ERC1155OrderPreSigned(
LibNFTOrder.TradeDirection direction,
address maker,
address taker,
uint256 expiry,
uint256 nonce,
IERC20TokenV06 erc20Token,
uint256 erc20TokenAmount,
LibNFTOrder.Fee[] fees,
IERC1155Token erc1155Token,
uint256 erc1155TokenId,
LibNFTOrder.Property[] erc1155TokenProperties,
uint128 erc1155TokenAmount
);

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);

152
docs/basics/orders.rst
View File

@ -89,10 +89,160 @@ The ``RFQOrder`` struct has the following fields:
+-----------------+-------------+----------------------------------------------------------------------------------------------------------------------------+
NFT Orders
===========
NFT orders in 0x V4 are optimized for this specific use case. They are up to 54% cheaper than alternatives currently on Ethereum.
Unlike 0x Limit orders, there is a `direction` of the trade, either buy or sell. ERC20's can be exchanged for either ERC721 or ERC1155.
Property based orders can also be created by specifying the properties field in the respective order.
A number of fees can be embedded in the order.
`NFT Swap SDK <https://docs.swapsdk.xyz/0x-v4>`__ is a friendly library that will help you easily create and consume NFT orders in 0x V4. You can find their `documentation here <https://docs.swapsdk.xyz/0x-v4>`__.
ERC721 Orders
*************
The ``ERC721Order`` struct has the following fields:
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| Field | Type | Description |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``direction`` | ``enum`` | The trade direction, either sell the NFT or buy the NFT |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``maker`` | ``address`` | The address of the maker, and signer, of this order. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``taker`` | ``address`` | Allowed taker address. Set to zero to allow any taker. [optional; default 0] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``expiry`` | ``uint256`` | The Unix timestamp in seconds when this order expires. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``nonce`` | ``uint256`` | Number used to uniquiely represent this order. Used for cancellations. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc20Token`` | ``address`` | The ERC20 token used to pay for the ERC721 token. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc20TokenAmount`` | ``uint256`` | The amount of erc20Token being sold. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``fees`` | ``Fees[]`` | An array of structs containing the fee data [optional] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc721Token`` | ``address`` | The ERC721 token. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc721TokenId`` | ``uint256`` | The ERC721 token id. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc721TokenProperties`` | ``Property[]`` | Properties to validate for a property based order. [optional] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
ERC1155 Orders
***************
The ``ERC1155Order`` struct has the following fields:
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| Field | Type | Description |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``direction`` | ``enum`` | The trade direction, either sell the NFT or buy the NFT |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``maker`` | ``address`` | The address of the maker, and signer, of this order. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``taker`` | ``address`` | Allowed taker address. Set to zero to allow any taker. [optional; default 0] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``expiry`` | ``uint256`` | The Unix timestamp in seconds when this order expires. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``nonce`` | ``uint256`` | Number used to uniquiely represent this order. Used for cancellations. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc20Token`` | ``address`` | The ERC20 token used to pay for the ERC721 token. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc20TokenAmount`` | ``uint256`` | The amount of erc20Token being sold. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``fees`` | ``Fees[]`` | An array of structs containing the fee data [optional] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc1155Token`` | ``address`` | The ERC1155 token. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc1155TokenId`` | ``uint256`` | The ERC1155 token id. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc1155TokenProperties`` | ``Property[]`` | Properties to validate for a property based order. [optional] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``erc1155TokenAmount`` | ``uin128`` | The ERC1155 amount. [required] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
NFT Order Property
******************
For Property based NFT orders, the properties have the following fields:
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| Field | Type | Description |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``propertyValidator`` | ``address`` | The address of the contract which implements `IPropertyValidator`. |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``propertyData`` | ``bytes`` | The address of the maker, and signer, of this order. |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
The property validator contract must implement the following interface when Property based orders are used.
.. code-block:: solidity
/// @dev Checks that the given ERC721/ERC1155 asset satisfies the properties encoded in `propertyData`.
/// Should revert if the asset does not satisfy the specified properties.
/// @param tokenAddress The ERC721/ERC1155 token contract address.
/// @param tokenId The ERC721/ERC1155 tokenId of the asset to check.
/// @param propertyData Encoded properties or auxiliary data needed to perform the check.
function validateProperty(
address tokenAddress,
uint256 tokenId,
bytes calldata propertyData
)
external
view;
NFT Order Fee
**************
For NFT orders with fees, the fees have the following fields:
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| Field | Type | Description |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``receipient`` | ``address`` | The receipient of the fees. |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``amount`` | ``uint256`` | The amount of fee to be paid to recipient. |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
| ``feeData`` | ``bytes`` | If provided the recipient (contract) will be called with this feeData [optional] |
+----------------------------+-----------------+------------------------------------------------------------------------------------------+
The contract must implement the following interface when the `feeData` is present.
.. code-block:: solidity
interface IFeeRecipient {
/// @dev A callback function invoked in the ERC721Feature for each ERC721
/// order fee that get paid. Integrators can make use of this callback
/// to implement arbitrary fee-handling logic, e.g. splitting the fee
/// between multiple parties.
/// @param tokenAddress The address of the token in which the received fee is
/// denominated. `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` indicates
/// that the fee was paid in the native token (e.g. ETH).
/// @param amount The amount of the given token received.
/// @param feeData Arbitrary data encoded in the `Fee` used by this callback.
/// @return success The selector of this function (0x0190805e),
/// indicating that the callback succeeded.
function receiveFeeCallback(
address tokenAddress,
uint256 amount,
bytes calldata feeData
)
external
returns (bytes4 success);
}
How To Sign
==============
Both Limit & RFQ orders must be signed by the `maker` or a registered order signer (`registerAllowedOrderSigner <./functions.html#registerallowedrfqorigins>`_). This signature is needed to fill an order, see `Basic Functionality <./functions.html>`_.
Orders must be signed by the `maker` or a registered order signer (`registerAllowedOrderSigner <./functions.html#registerallowedrfqorigins>`_). This signature is needed to fill an order, see `Basic Functionality <./functions.html>`_.
The protocol accepts signatures defined by the following struct:

4
docs/conf.py
View File

@ -60,9 +60,9 @@ copyright = u'2016, ZeroEx Inc'
# built documents.
#
# The short X.Y version.
version = '4.0'
version = '4.1'
# The full version, including alpha/beta/rc tags.
release = '4.0'
release = '4.1'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

51
docs/scripts/generate_addresses.py
View File

@ -12,7 +12,6 @@ sections = [
"name": "Exchange V4",
"contracts": [
'exchangeProxy',
'exchangeProxyAllowanceTarget',
'exchangeProxyFlashWallet',
'exchangeProxyGovernor',
'exchangeProxyLiquidityProviderSandbox',
@ -50,18 +49,43 @@ sections = [
}
]
def printRow(contract, address):
etherscanLink = "%s/%s"%("https://etherscan.io/address/", address)
print(" %s, `%s <%s>`_"%(contract, address, etherscanLink))
networks = {
'1': 'Ethereum',
'10': 'Optimism',
'56': 'Binance Smart Chain',
'137': 'Polygon',
'43114': 'Avalanche',
'250': 'Fantom',
'42220': 'Celo',
}
def printTable(contracts, addresses):
etherscanByNetwork = {
'1': 'https://etherscan.io/address',
'10': 'https://optimistic.etherscan.io/address',
'56': 'https://bscscan.com/address',
'137': 'https://polygonscan.com/address',
'43114': 'https://snowtrace.io/address',
'250': 'https://ftmscan.com/address',
'42220': 'https://explorer.celo.org/address',
}
def getLinkableAddress(address, network):
etherscanLink = "%s/%s"%(etherscanByNetwork[network], address)
return "`%s <%s>`__"%(address, etherscanLink)
def printRow(contract, address, network):
etherscanLink = "%s/%s"%(etherscanByNetwork[network], address)
print(" %s, %s"%(contract, getLinkableAddress(address, network)))
def printTable(contracts, addresses, network):
print(".. csv-table::\n")
for contract in contracts:
if isinstance(addresses[contract], unicode):
printRow(contract, addresses[contract])
if isinstance(addresses[contract], str):
printRow(contract, addresses[contract], network)
else:
for contract,address in addresses[contract].items():
printRow(contract, address)
printRow(contract, address, network)
print(
@ -72,6 +96,8 @@ Addresses
.. note::
This page is auto-generated. See the `contract-addresses <https://github.com/0xProject/protocol/blob/development/packages/contract-addresses/addresses.json>`_ package for an exhaustive list of contracts across all networks.
The Exchange Proxy may have different addresses on various networks, see the `Exchange Proxy Addresses <./addresses.html#exchange-proxy-addresses>`__ table for an exhaustive list.
'''
)
@ -79,6 +105,13 @@ with open('../packages/contract-addresses/addresses.json') as f:
addresses = json.load(f)
for section in sections:
print("%s\n==================="%(section["name"]))
printTable(section["contracts"], addresses["1"])
printTable(section["contracts"], addresses["1"], "1")
print("\n\n")
print("Exchange Proxy Addresses \n=========================")
print("Note: Some addresses have changed across various networks\n")
print(".. csv-table::\n")
for network in networks:
# etherscanLink = "%s/%s"%("https://etherscan.io/address/", address)
# print(" %s, `%s <%s>`_"%(contract, address, etherscanLink))
print(" %s, %s"%(networks[network], getLinkableAddress(addresses[network]["exchangeProxy"], network)))