Doc update (#675)

* Update existing protocol docs to point to protocol-specific resources

Remove documentation of outdated/irrelevant portions of the protocol

* pin jinja version to try to fixbuild failure. (#711)

---------

Co-authored-by: Eric Wong <ewong@Erics-MBP.fios-router.home>

docs/architecture/governor.rst

@@ -62,16 +62,16 @@ Function timelocks are represented in days, where one day is equivalent to 86,40
 .. csv-table::
     :header: "Contract", "Function", "Selector", "Timelock"
 
-    AllowanceTarget, ``addAuthorizedAddress``, ``42f1181e``, 2 days
+    AllowanceTarget, ``addAuthorizedAddress``, ``42f1181e``, 2 day
     AllowanceTarget, ``removeAuthorizedAddress``, ``70712939``, 0 days
     AllowanceTarget, ``removeAuthorizedAddressAtIndex``, ``9ad26744``, 0 days
-    Governor, ``registerFunctionCall``, ``751ad560``, 2 days
-    ExchangeProxy, ``extend``, ``6eb224cb``, 2 days
-    ExchangeProxy, ``migrate``, ``261fe679``, 2 days
+    Governor, ``registerFunctionCall``, ``751ad560``, 2 day
+    ExchangeProxy, ``extend``, ``6eb224cb``, 2 day
+    ExchangeProxy, ``migrate``, ``261fe679``, 2 day
     ExchangeProxy, ``rollback``, ``9db64a40``, 0 days
-    ExchangeProxy, ``setQuoteSigner``, ``<deprecation in progress>``, 2 days
-    ExchangeProxy, ``setTransformerDeployer``, ``87c96419``, 2 days
-    ExchangeProxy, ``transferOwnership``, ``f2fde38b``, 2 days
+    ExchangeProxy, ``setQuoteSigner``, ``<deprecation in progress>``, 2 day
+    ExchangeProxy, ``setTransformerDeployer``, ``87c96419``, 2 day
+    ExchangeProxy, ``transferOwnership``, ``f2fde38b``, 2 day
     StakingProxy, ``addExchangeAddress``, ``8a2e271a``, 14 days
     StakingProxy, ``removeExchangeAddress``, ``01e28d84``, 14 days
     StakingProxy, ``attachStakingContract``, ``66615d56``, 14 days

docs/architecture/overview.rst

@@ -2,7 +2,7 @@
 Overview
 ###############################
 
-The 0x Exchange implements a delegate-call proxy pattern to create a system of composable smart contracts. This architecture enables 0x to innovate with minimal friction alongside the growing DeFi ecosystem.
+The `ZeroEx` (Exchange Proxy) contract implements a delegate-call proxy pattern to create a system of composable smart contracts. This architecture enables 0x Protocol to innovate with minimal friction alongside the growing DeFi ecosystem.
 
 The diagram below illustrates our system (click to enlarge).
 
@@ -24,13 +24,7 @@ The table below defines our smart contract nomenclature.
 +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `Flash Wallet <./flash_wallet.html>`_                 | The Flash Wallet is a sandboxed escrow contract that holds funds for Transformers to operate on. For example, the ``WETHtransformer`` wraps any Ether in the Flash Wallet.                    |
 +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `Allowance Target <../basics/allowances.html>`_       | Users set their allowances on this contract. It is scheduled to be deprecated after the official V4 release in January, 2021. After which point allowances will be set directly on the Proxy. |
-+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `Governor <./governor.html>`_                         | A MultiSig that governs trusted contracts in the system: Proxy, Features, Flash Wallet.                                                                                                       |
-+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `Transformer Deployer <./transformer_deployer.html>`_ | Deploys Transformers. A transformer is authenticated using a nonce of the Transformer Deployer.                                                                                               |
-+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| `Fee Collectors <./fee_collectors.html>`_             | `Protocol fees <../basics/protocol_fees.html>`_ are paid into these contracts at time-of-fill.                                                                                                |
+| `Governor <./governor.html>`_                         | A smart contract that governs trusted contracts in the system: Proxy, Features, Flash Wallet.                                                                                                 |
 +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `PLP Sandbox <./plp_sandbox.html>`_                   | `PLP <../advanced/plp.html>`_ liquidity providers are called from this sandbox.                                                                                                               |
 +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

docs/architecture/proxy.rst

@@ -2,37 +2,22 @@
 Proxy
 ###############################
 
-The `ZeroEx <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/ZeroEx.sol>`_ contract implements a per-function proxy pattern. Every function registered to the proxy contract can have a distinct implementation contract. Implementation contracts are called “features” and can expose multiple, related functions. Since features can be upgraded independently, there will no longer be a collective “version” of the API, defaulting to a rolling release model. The ZeroEx contract’s only responsibility is to route (delegate) calls to per-function implementation contracts through its fallback.
+The `ZeroEx <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/ZeroEx.sol>`_ contract (also called Exchange Proxy or EP) is the main contract that manages the process and performs the exchange of assets. It implements a per-function proxy pattern where each function can have a distinct implementation contract, also known as "features". The `ZeroEx` contract's sole responsibility is to maintain a mapping of "features" to implementation contracts and route (delegate) calls to per-function implementation contracts through its fallback mechanism. 
 
 .. image:: ../_static/img/proxy.png
     :align: center
     :scale: 100%
 
-View the code for the Proxy `here <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/ZeroEx.sol>`_. There is also a `gas-optimized implementation <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/ZeroExOptimized.sol>`_ that may be put into production in the future (there is a lot of overhead for our integrators when redeploying this contract).
+View the code for the Proxy `here <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/ZeroEx.sol>`_. The deployed contract address for each network can be found in `here <https://github.com/0xProject/protocol/blob/development/packages/contract-addresses/addresses.json>`_.
 
-Bootstrapping
-=============
-The ZeroEx contract comes pre-loaded with only one Feature: `Bootstrap <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/features/BootstrapFeature.sol>`_. This exposes a ``bootstrap()`` function that can only be called by the deployer. This function does a few things:
-
-1. De-register the bootstrap() function, which prevents it being called again.
-2. Self-destruct.
-3. Delegatecall the bootstrapper target contract and call data.
-
-.. code-block:: solidity
-
-    // Execute a bootstrapper in the context of the proxy.
-    function bootstrap(address target, bytes callData) external
-
-Below is the bootstrap workflow (click to enlarge).
-
-.. image:: ../_static/img/bootstrap.png
-    :align: center
-    :scale: 70%
+Deployment
+==========
+At deployment, the ``ZeroEx`` contract goes through an ``InitialMigration`` that bootstraps two core features to the proxy pattern: Function Registry and Ownership.
 
 Function Registry
 =================
 
-One of the initial features InitialMigration bootstraps into the ZeroEx contract is the function registry feature, SimpleFunctionRegistry. This feature exposes the following function registry management features: ``extend()`` and ``rollback()``.
+``SimpleFunctionRegistry`` is one of the initial and core features of the `ZeroEx` contract boostrapped in during the ``InitialMigration``. This feature exposes the following function registry management features: ``extend()`` and ``rollback()``.
 
 Call ``extend()`` to register a new function (selector) and implementation (address). This also maintains a history of past implementations so we can roll back to one, if needed.
 
@@ -54,7 +39,7 @@ Call ``rollback()`` to revert a function implementation to a prior version in it
 
 Ownership
 =========
-Another Feature, ``InitialMigration``, bootstraps into the proxy is the Ownable feature. This exposes ownership management functions: ``transferOwnership()`` and ``owner()``. This feature also enables ubiquitous modifiers such as onlyOwner, so it is an implicit dependency of nearly every other feature.
+``Ownable`` is another initial and core feature of the `ZeroEx` contract that is bootstrapped into the proxy during the ``InitialMigration``. This exposes ownership management functions: ``transferOwnership()`` and ``getOwner()``. This feature also enables ubiquitous modifiers such as onlyOwner, so it is an implicit dependency of nearly every other feature.
 
 .. code-block:: solidity
 
@@ -256,3 +241,24 @@ Functions can be re-entered by default; those secured by the ``nonReentrant`` mo
 **Colliding Function Selectors**
 
 We manually ensure that function selectors do not collide during PR's. See the `Feature Checklist <./features.html#best-practices>`_ for a complete list of our best practices on Feature Development.
+
+Initial Bootstrapping
+=====================
+
+The way that the initial bootstrapping is accomplished is through the ``bootstrap()`` function that can only be called by the deployer. Check `here <https://github.com/0xProject/protocol/blob/development/contracts/zero-ex/contracts/src/features/BootstrapFeature.sol>`_ to see the full boostrapping feature.
+
+This function does a few things:
+1. De-register the bootstrap() function, which prevents it being called again.
+2. Self-destruct.
+3. Delegatecall the bootstrapper target contract and call data.
+
+.. code-block:: solidity
+
+    // Execute a bootstrapper in the context of the proxy.
+    function bootstrap(address target, bytes callData) external
+
+Below is the bootstrap workflow (click to enlarge).
+
+.. image:: ../_static/img/bootstrap.png
+    :align: center
+    :scale: 70%

docs/basics/orders.rst

@@ -295,9 +295,9 @@ In both cases, the ``@0x/protocol-utils`` package simplifies generating these si
 
 The Orderbook
 =======================
-Orders are shared through a decentralized and permissionless network, called `0x Mesh <https://0x.org/mesh>`_. The simplest way to post and discover orders is through `0x API <https://0x.org/api>`_. See `this guide <https://0x.org/docs/guides/market-making-on-0x>`_ tailored for Market Makers.
+Orders can be hosted by any server and are usually represented as a JSON object off-chain. For example, one off-chain way to post and discover orders is through `0x API <https://0x.org/api>`_.
 
-Orders are usually represented as a JSON object off-chain. Below is a table represention and example of how orders should be formatted off-chain.
+Below is a table represention and example of how orders should be formatted off-chain.
 
 JSON representation of RFQ Orders
 *********************************

docs/basics/signatures.rst

@@ -0,0 +1,75 @@
+Signatures
+==========
+
+Signatures are used in several places in 0x Protocol to prove an actor
+has agreed to the behavior in some off-chain message.
+
+Signatures are represented by the following struct:
+
+.. code:: solidity
+
+   struct Signature {
+       // How to validate the signature.
+       SignatureType signatureType;
+       // EC Signature data.
+       uint8 v;
+       // EC Signature data.
+       bytes32 r;
+       // EC Signature data.
+       bytes32 s;
+   }
+
+Where ``SignatureType`` is:
+
+.. code:: solidity
+
+   enum SignatureType {
+       ILLEGAL,
+       INVALID,
+       EIP712,
+       ETHSIGN,
+       PRESIGNED
+   }
+
+Descriptions of the valid signature types follow.
+
+**EIP712 (``2``)**
+
+This is the signature type typically used when an order is signed
+through a UI, such as Metamask. This is commonly achieved by calling
+some variant of the ``eth_signTypedData`` (which fully utilizes EIP712)
+JSONRPC command on the Ethereum provider.
+
+It can also be generated in a headless manner using a standard
+``ecsign()`` implementation
+(`example <https://github.com/ethereumjs/ethereumjs-util/blob/master/docs/modules/_signature_.md#const-ecsign>`__)
+by re-hashing the `canonical order
+hash <signatures.md#limit-order-hashes>`__ with a prefix as follows and
+signing the result:
+
+.. code:: solidity
+
+   eip712HashToSign = keccak256(abi.encodePacked(
+       "\x19Ethereum Signed Message:\n32",
+       orderHash
+   ));
+
+ETHSIGN (``3``)
+^^^^^^^^^^^^^^^
+
+This is the signature type typically used when an order is signed in a
+headless environment (e.g., script or backend). This commonly achieved
+by calling the ``eth_sign`` JSONRPC command on the Ethereum provider or,
+perhaps more straight-forwardly, using a standard ``ecsign()``
+implementation
+(`example <https://github.com/ethereumjs/ethereumjs-util/blob/master/docs/modules/_signature_.md#const-ecsign>`__).
+Unlike the ``EIP712`` signature type, the hash to sign is simply the
+`canonical order hash <signatures.md#limit-order-hashes>`__ (no prefix).
+
+PRESIGNED (``4``)
+^^^^^^^^^^^^^^^^^
+
+This signature type is used exclusively with NFT orders (721 and 1155)
+for now. This value indicates that the order maker has previously marked
+the order as fillable on-chain. The remaining fields in the
+``Signature`` struct will be ignored.