diff --git a/docs/advanced/plp.rst b/docs/advanced/plp.rst index 274aa92d1b..4428e37cf7 100644 --- a/docs/advanced/plp.rst +++ b/docs/advanced/plp.rst @@ -7,59 +7,80 @@ PLP (Pluggable Liquidity PLP) enables anyone to extend the 0x Protocol with thei Implementing a Liquidity Provider ================================= -The only requirement is that the provider implements the interface in `ILiquidityProviderSandbox `_. +The only requirement is that the provider implements the interface in `ILiquidityProvider `_. +Note that ``sellEthForToken`` and ``sellTokenForEth`` do not need to be implemented if the liquidity provider does not trade ETH/WETH. .. code-block:: solidity - /// @dev Calls `sellTokenForToken` on the given `provider` contract to - /// trigger a trade. - /// @param provider The address of the on-chain liquidity provider. + /// @dev Trades `inputToken` for `outputToken`. The amount of `inputToken` + /// to sell must be transferred to the contract prior to calling this + /// function to trigger the trade. /// @param inputToken The token being sold. /// @param outputToken The token being bought. /// @param recipient The recipient of the bought tokens. /// @param minBuyAmount The minimum acceptable amount of `outputToken` to buy. - /// @param auxiliaryData Auxiliary data supplied to the `provider` contract. - function executeSellTokenForToken( - address provider, + /// @param auxiliaryData Arbitrary auxiliary data supplied to the contract. + /// @return boughtAmount The amount of `outputToken` bought. + function sellTokenForToken( address inputToken, address outputToken, address recipient, uint256 minBuyAmount, bytes calldata auxiliaryData ) - external; + external + returns (uint256 boughtAmount); - /// @dev Calls `sellEthForToken` on the given `provider` contract to - /// trigger a trade. - /// @param provider The address of the on-chain liquidity provider. + /// @dev Trades ETH for token. ETH must either be attached to this function + /// call or sent to the contract prior to calling this function to + /// trigger the trade. /// @param outputToken The token being bought. /// @param recipient The recipient of the bought tokens. /// @param minBuyAmount The minimum acceptable amount of `outputToken` to buy. - /// @param auxiliaryData Auxiliary data supplied to the `provider` contract. - function executeSellEthForToken( - address provider, + /// @param auxiliaryData Arbitrary auxiliary data supplied to the contract. + /// @return boughtAmount The amount of `outputToken` bought. + function sellEthForToken( address outputToken, address recipient, uint256 minBuyAmount, bytes calldata auxiliaryData ) - external; + external + payable + returns (uint256 boughtAmount); - /// @dev Calls `sellTokenForEth` on the given `provider` contract to - /// trigger a trade. - /// @param provider The address of the on-chain liquidity provider. + /// @dev Trades token for ETH. The token must be sent to the contract prior + /// to calling this function to trigger the trade. /// @param inputToken The token being sold. /// @param recipient The recipient of the bought tokens. /// @param minBuyAmount The minimum acceptable amount of ETH to buy. - /// @param auxiliaryData Auxiliary data supplied to the `provider` contract. - function executeSellTokenForEth( - address provider, + /// @param auxiliaryData Arbitrary auxiliary data supplied to the contract. + /// @return boughtAmount The amount of ETH bought. + function sellTokenForEth( address inputToken, - address recipient, + address payable recipient, uint256 minBuyAmount, bytes calldata auxiliaryData ) - external; + external + returns (uint256 boughtAmount); + + /// @dev Quotes the amount of `outputToken` that would be obtained by + /// selling `sellAmount` of `inputToken`. + /// @param inputToken Address of the taker token (what to sell). Use + /// the wETH address if selling ETH. + /// @param outputToken Address of the maker token (what to buy). Use + /// the wETH address if buying ETH. + /// @param sellAmount Amount of `inputToken` to sell. + /// @return outputTokenAmount Amount of `outputToken` that would be obtained. + function getSellQuote( + address inputToken, + address outputToken, + uint256 sellAmount + ) + external + view + returns (uint256 outputTokenAmount); Trading with a Liquidity Provider @@ -98,4 +119,4 @@ To trade with a liquidity provider use the ``sellToLiquidityProvider`` function. This function transfers tokens from ``msg.sender`` to the liquidity provider then executes the trade through a sandboxed contract external to the Exchange Proxy. The sandbox then executes the trade through the provider. This function then transfers the output tokens to the ``recipient``. -This function will emit a `LiquidityProviderSwap <../basics/events.html#liquidityproviderswap>`_ event if the trade succeeds. It will revert if the amount of ``outputToken`` returned by the Liquidity Provider is less than ``minBuyAmount``. \ No newline at end of file +This function will emit a `LiquidityProviderSwap <../basics/events.html#liquidityproviderswap>`_ event if the trade succeeds. It will revert if the amount of ``outputToken`` returned by the Liquidity Provider is less than ``minBuyAmount``.