add EP specs

Author: merklejerk

exchange-proxy/exchange-proxy.md

@@ -0,0 +1,185 @@
+# Arbitrary ERC20 Transformations
+
+## Background
+
+Integrations have taught us that there is no one-size-fits-all solution to a swap function. Different integrators will have different needs. Some prefer to interact with ETH over WETH, others want to collect affiliate fees, and we may see some that want to interact using wrapped tokens (cUSDC and the like).
+
+## The `transformERC20()` Function
+
+A theme common to most of these wants, including a simple market buy/sell, is that a taker is trying to transform X input tokens into Y output tokens. With this understanding, we can create a generalized `transformERC20()` function that only does the following:
+
+1. Take X input tokens from the taker.
+2. Perform arbitrary transformations (provided by the taker) on the tokens we hold.
+3. Validate that the taker has received Y output tokens.
+
+We don’t particularly care what goes on inside the transformations so long as the taker winds up receiving the required amount of output tokens at the end of it. This is similar to how ERC20Bridges operate, in that the `ERC20BridgeProxy` does not know what the bridges are doing, but asserts at the end that the taker has received enough maker tokens
+
+### Transformers
+
+We define each of our desired transformations as “Transformer” contracts. Similar to bridge contracts, transformers typically receive tokens and produce some kind of “output” token (but aren’t required to do either of these). Some example transformers we would have:
+
+* WethAbstractionTransformer:
+    * If WETH is received, unwrap to ETH
+    * If ETH is received, wrap to WETH
+* AffiliateFeeTransformer:
+    * Transfers % of the tokens received to an affiliate address.
+* ProtocolFeeBrokerTransformer:
+    * Converts % of the tokens received into ETH, possibly by executing another swap.
+* PayTakerTransformer:
+    * Transfers tokens directly to the taker.
+* FillQuoteTransformer:
+    * Perform a market buy/sell on a set of orders, most likely generated by 0x-API.
+* CompoundTokenTransformer:
+    * If DAI is received, convert to cDAI
+    * If USDC is received, convert to cUSDC
+    * If cDAI is received, convert to DAI
+    * if cUSDC is received, convert to USDC
+
+### Flash Wallets
+
+A big difference from bridge contracts is that we `delegatecall` into transformers instead of performing a regular `call`.  This is to avoid the massive gas overhead that would be incurred if we had to transfer intermediate tokens to each transformer contract. However, we don’t want to perform the `delegatecall` in the context of the Exchange proxy because that would give transformers full control over the Exchange proxy.
+
+So instead we use a middle-man contract called a `FlashWallet`. The wallet contract will hold all intermediate token balances and perform `delegatecall`s to the individual transformers, in a context separate from the Exchange proxy. The `TransformERC20` feature will hold a single `FlashWallet` contract instance which can be reused by `transformERC20()` all operations.
+
+The wallet instance can be (re)created with `createTransformWallet()`, which is callable by the owner/governor. This allows us to deploy a fresh wallet in case we somehow break the old one, like if we accidentally `selfdestruct` it or clobber its state.
+
+The wallet also works with ERC1155 and ERC223 tokens by implementing the required fallbacks for those standards. This allows transformers to hold ERC1155 and ERC223 intermediate assets. If we decide to add support for more tokens, we will have to upgrade the `TransformERC20` feature since the FlashWallet bytecode is hardcoded into it.
+
+### Transformation Pipeline
+
+`transformERC20()` executes each Transformer in sequence, manipulating the token balance held by the wallet. The final transformer will simply transfer the output token directly to the taker. This creates a composable pipeline of operations/transitions.
+
+![transform-pipeline](https://raw.githubusercontent.com/0xProject/0x-protocol-specification/master/exchange-proxy/img/transform-pipeline.png)
+
+For example, if a taker wanted to do the following:
+
+1. Pay ETH
+2. Convert to WETH
+3. Fill a WETH → USDC quote
+4. Pay affiliate fee in USDC
+5. Wrap the USDC in cUSDC
+
+It might look like:
+
+
+![transform-example](https://raw.githubusercontent.com/0xProject/0x-protocol-specification/master/exchange-proxy/img/transform-example.png)
+
+### Locking Down Transformers
+
+Transformers need to be permissioned since they’re taking control of the wallet instance. Though no loss of funds should be able to occur in otherwise,  opening up wallets to arbitrary transformers could lead to griefing by transformers rendering the wallets unusable (e.g., `selfdestruct`).
+
+If we maintained a registry of allowed Transformer contracts on the Exchange proxy, changes would likely have to go through the governor and be subject to timelocks, which defeats the nimbleness aspect of this entire architecture. This also incurs an `SLOAD`. Instead, we can adopt the pattern of using a single, known deployer address to deploy all Transformers. Instead of taking an address of a transformer, the `transformERC20()` function takes a “deployment nonce,” which is the nonce the trusted deployer had when deploying the transformer. The address of the transformer will be derived from this value.
+
+A consequence of this approach is that a transformer will always be valid. If the transformer can render the state of the `FlashWallet` invalid, it can be perpetually used to grief the system. The recommendation here is to expose a self-destructing `die()` function on all transformers which:
+
+* Is only callable by the deployer/owner.
+* Checks that `address(this) == _implementation` to ensure it always self-destructs in its own context.
+
+## Key Benefits
+
+* Composable flexibility
+    * Every integrator/taker has different needs. Allowing the taker to compose their own operations means they’re more likely to get the behavior they want.
+* Rapid development
+    * By separating out transformation logic from the Exchange proxy, we can iterate on these operations much more quickly.
+* Peace-of-mind
+    * By asserting that the taker has received the required amount of output tokens at the end, we can treat transformers as black boxes and have reasonable certainty that the taker is not being swindled.
+* Novel use cases
+    * The pluggable nature of this function means it is not limited to fills. One could use it to perform many common DeFi operations in a single transaction.
+
+###
+
+## Implementation
+
+The feature interface:
+
+```solidity
+interface ITransformERC20 {
+
+    /// @dev Defines a transformation to run in `transformERC20()`.
+    struct Transformation {
+        // The deployment nonce of the transformer.
+        // This is the nonce the deployer had when deploying the transformer.
+        // The address of the transformer will be derived from this value.
+        uint32 deploymentNonce;
+        // Arbitrary data to pass to the transformer.
+        bytes data;
+    }
+
+    /// @dev Executes a series of transformations to convert an ERC20 `inputToken`
+    ///      to an ERC20 `outputToken`.
+    /// @param inputToken The token being provided by the sender.
+    ///        If `0xeee...`, ETH is implied and should be provided with the call.`
+    /// @param outputToken The token to be acquired by the sender.
+    ///        `0xeee...` implies ETH.
+    /// @param inputTokenAmount The amount of `inputToken` to take from the sender.
+    ///        May be `uint256(-1)` to indicate the maximum transferrable.
+    /// @param minOutputTokenAmount The minimum amount of `outputToken` the sender
+    ///        must receive for the entire transformation to succeed.
+    /// @param transformations Sequence of transformations to apply to the token
+    ///        balances.
+    /// @return outputTokenAmount The amount of `outputToken` received by the sender.
+    function transformERC20(
+        IERC20TokenV06 inputToken,
+        IERC20TokenV06 outputToken,
+        uint256 inputTokenAmount,
+        uint256 minOutputTokenAmount,
+        Transformation[] calldata transformations
+    )
+        external
+        payable
+        returns (uint256 outputTokenAmount);
+}
+```
+
+The transformer interface:
+
+```solidity
+/// @dev A transformation callback used in `TransformERC20.transformERC20()`.
+interface IERC20Transformer {
+
+    /// @dev Called from `TransformERC20.transformERC20()`, AFTER the requested
+    ///      ERC20 tokens have been transferred to this contract.
+    ///      If ETH is requested, it will be attached to this call.
+    ///      Some or all of the caller's balance of requested tokens/ETH will be
+    ///      transferred, and any unused tokens/ETH should be returned to
+    ///      `msg.sender` before returning.
+    /// @param callDataHash The hash of the `TransformERC20.transformERC20()` calldata.
+    /// @param taker The taker address (caller of `TransformERC20.transformERC20()`).
+    /// @param data Arbitrary data to pass to the transformer.
+    /// @return success The success bytes (`LibERC20Transformer.TRANSFORMER_SUCCESS`).
+    function transform(
+        bytes32 callDataHash,
+        address taker,
+        bytes calldata data
+    )
+        external
+        payable
+        returns (bytes memory rlpDeploymentNonce);
+}
+```
+
+# TokenSpender
+
+We need a way to transfer funds from the taker into the Exchange proxy temporarily so we can perform transformations on it. We could simply have the taker set an allowance for the Exchange proxy, but this comes with some risk:
+
+* Lack of separation of complex logic vs access to funds.
+* No easy way to detach allowances in case of a critical vulnerability.
+* Allowances do not migrate if we ever redeploy the Exchange proxy.
+* Dangling allowances if we decide to migrate the Exchange proxy to use the V3 asset proxies for allowances.
+
+So we opt for something akin to the role of asset proxies in V3, where takers must set their allowance to a separate, specialized spender contract accessible by the Exchange proxy. However, instead of having a single allowance contract for each asset type, we instead have a **single**, universal spender contract. Takers can get the address of this contract with `getAllowanceTarget()`.
+
+This universal allowance contract has a single `executeCall()` function which blindly `call`s calldata on the caller’s behalf. This contract is akin the `FlashWallet` used by `transformERC20()` with some notable differences:
+
+* Implements the `Authorizable` mixin.
+    * Owner will be set to the governor.
+    * The `ZeroEx` contract will be the sole authorized address.
+* Cannot perform a `delegatecall`. Instead exposes an (authority-only) `executeCall()` function that simply forwards a call.
+* Is never intended to hold a balance.
+
+Through `executeCall()`, the Exchange proxy can call `transferFrom()` in the `AllowanceTarget`’s context to move taker funds. A dedicated feature, `TokenSpender`, will wrap this functionality with convenience functions such as `_spendERC20Tokens(token, from to, amount)`.
+
+
+![token-spender](https://raw.githubusercontent.com/0xProject/0x-protocol-specification/master/exchange-proxy/img/token-spender.png)
+
+The `AllowanceTarget` instance is owned by the same owner of the `ZeroEx` contract, so it can be detached in an emergency or a migration.