uniswap-python · ErikBjare · May 21, 2021 · May 19, 2021 · May 19, 2021 · May 19, 2021
diff --git a/README.md b/README.md
@@ -32,178 +32,10 @@ Documentation is available at https://uniswap-python.com/
 
 ## Getting Started
 
-This README is documentation on the syntax of the python client presented in this repository. See function docstrings for full syntax details.
-
-This library attempts to present a clean interface to Uniswap, but in order to use it to its full potential, you must familiarize yourself with the official Uniswap documentation.
-
-*  https://docs.uniswap.io/
-
-You may manually install the project or use pip:
-
-```python
-pip install uniswap-python
-
-# or
-
-pip install git+git://github.com/shanefontaine/uniswap-python.git
-```
-
-### Environment Variables
-The program expects an environment variables to be set in order to run the program. You can use an Infura node, since the transactions are being signed locally and broadcast as a raw transaction. The environment variable is:
-
-```
-PROVIDER  # HTTP Provider for web3
-```
-
-### Gas pricing
-
-To modify the gas pricing strategy you need to pass a custom `Web3` instance to the `Uniswap` constructor. You can find details for how to configure Web3 gas strategies in their [documentation](https://web3py.readthedocs.io/en/stable/gas_price.html).
-
-### Examples and API
-
-**Note:** These examples are in the process of being moved to the [docs](https://shanefontaine.github.io/uniswap-python/).
-
-The `Uniswap` class takes several optional parameters, read the code to see which ones are available.
-
-```python
-from uniswap import Uniswap
-address = "YOUR ADDRESS"          # or "0x0000000000000000000000000000000000000000", if you're not making transactions
-private_key = "YOUR PRIVATE KEY"  # or None, if you're not going to make transactions
-uniswap_wrapper = Uniswap(address, private_key, version=2)  # pass version=2 to use Uniswap v2
-eth = "0x0000000000000000000000000000000000000000"
-bat = "0x0D8775F648430679A709E98d2b0Cb6250d2887EF"
-dai = "0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359"
-```
-
-#### Price Methods
-
-> **Note:** These methods assume a certain route for the swap to take, which may not be the optimal route. See https://github.com/shanefontaine/uniswap-python/issues/69 for details.
-
-These methods return the price as an integer in the smallest unit of the token. You need to ensure that you know how many decimals the token you're trying to trade uses to get prices in the common decimal format. See https://github.com/shanefontaine/uniswap-python/issues/12 for details.
-
-Decimals for common tokens:
-
- - ETH, DAI, and BAT uses 18 decimals (as you can see in code below)
- - WBTC uses 8 decimals
- - USDC and USDT uses 6 decimals
-
-You can look up the number of decimals used by a particular token by looking up the contract on Etherscan. As an example, here is the one for WBTC: https://etherscan.io/token/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599
-
-*  [get_eth_token_input_price](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L416)
-```python
-# Get the public price for ETH to Token trades with an exact input.
-uniswap_wrapper.get_eth_token_input_price(bat, 1*10**18)
-uniswap_wrapper.get_eth_token_input_price(dai, 5*10**18)
-```
-
-*  [get_token_eth_input_price](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L437)
-```python
-# Get the public price for token to ETH trades with an exact input.
-uniswap_wrapper.get_token_eth_input_price(bat, 1*10**18)
-uniswap_wrapper.get_token_eth_input_price(dai, 5*10**18)
-```
-
-*  [get_eth_token_output_price](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L426)
-```python
-# Get the public price for ETH to Token trades with an exact output
-uniswap_wrapper.get_eth_token_output_price(bat, 1*10**18)
-uniswap_wrapper.get_eth_token_output_price(dai, 5*10**18)
-```
-
-*  [get_token_eth_output_price](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L448)
-```python
-# Get the public price for token to ETH trades with an exact output.
-uniswap_wrapper.get_token_eth_output_price(bat, 1*10**18)
-uniswap_wrapper.get_token_eth_output_price(dai, 5*10**18)
-```
-
-#### Trading
-
-> **Note:** The same route assumptions and need for handling decimals apply here as those mentioned in the previous section.
-
-* make_trade
-  * eth_to_token_input
-    * [ethToTokenSwapInput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L127)
-    * [ethToTokenTransferInput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L162)
-  * token_to_eth_input
-    * [tokenToEthSwapInput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L202)
-    * [tokenToEthTransferInput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L232)
-  * token_to_token_input
-    * [tokenToTokenSwapInput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L271)
-    * [tokenToTokenTransferInput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L307)
-
-```python
-# Make a trade based on the input parameters
-uniswap_wrapper.make_trade(eth, bat, 1*10**18) # calls _eth_to_token_input
-uniswap_wrapper.make_trade(bat, eth, 1*10**18) # calls _token_to_eth_input
-uniswap_wrapper.make_trade(bat, dai, 1*10**18) # calls _token_to_token_input
-uniswap_wrapper.make_trade(eth, bat, 1*10**18, "0x123...") # calls _eth_to_token_input
-```
-
-* make_trade_output
-  * eth_to_token_swap_output
-    * [ethToTokenSwapOutput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L167)
-    * [ethToTokenTransferOutput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L197)
-  * token_to_eth_swap_output
-    * [tokenToEthSwapOutput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L237)
-    * [tokenToEthTransferOutput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L266)
-  * token_to_token_swap_output
-    * [tokenToTokenSwapOutput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L312)
-    * [tokenToTokenTransferOutput](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L349))
-
-```python
-# Make a trade where the output qty is known based on the input parameters
-uniswap_wrapper.make_trade_output(eth, bat, 1*10**18) # calls _eth_to_token_swap_output
-uniswap_wrapper.make_trade_output(bat, eth, 1*10**18) # calls _token_to_eth_swap_output
-uniswap_wrapper.make_trade_output(bat, dai, 1*10**18, "0x123...") # calls _token_to_token_swap_output
-```
-
-#### Fee Methods
-*  [get_fee_maker](https://docs.uniswap.io/)
-```python
-uniswap_wrapper.get_fee_maker()
-```
-
-*  [get_fee_taker](https://docs.uniswap.io/)
-```python
-uniswap_wrapper.get_fee_taker()
-```
-
-
-#### ERC20 Pool Methods (v1 only)
-*  [get_ex_eth_balance](https://docs.uniswap.io/smart-contract-integration/vyper)
-```python
-# Get the balance of ETH in an exchange contract.
-uniswap_wrapper.get_ex_eth_balance(bat)
-```
-
-*  [get_ex_token_balance](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L469)
-```python
-# Get the balance of a token in an exchange contract.
-uniswap_wrapper.get_ex_token_balance(bat)
-```
-
-*  [get_exchange_rate](https://github.com/Uniswap/uniswap-frontend/blob/master/src/pages/Pool/AddLiquidity.js#L351)
-```python
-# Get the exchange rate of token/ETH
-uniswap_wrapper.get_exchange_rate(bat)
-```
-
-#### Liquidity Methods (v1 only)
-
-*  [add_liquidity](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L48)
-```python
-# Add liquidity to the pool.
-uniswap_wrapper.add_liquidity(bat, 1*10**18)
-```
-
-*  [remove_liquidity](https://github.com/Uniswap/contracts-vyper/blob/master/contracts/uniswap_exchange.vy#L83)
-```python
-# Remove liquidity from the pool.
-uniswap_wrapper.remove_liquidity(bat, 1*10**18)
-```
+See our [Getting started guide](https://uniswap-python.com/getting-started.html) in the documentation.
 
 ## Testing
+
 Unit tests are under development using the pytest framework. Contributions are welcome!
 
 Test are run on a fork of the main net using ganache-cli. You need to install it with `npm install -g ganache-cli` before running tests.

diff --git a/docs/api.rst b/docs/api.rst
@@ -9,9 +9,23 @@ Uniswap class
 .. autoclass:: Uniswap
    :members:
 
+Token class
+-----------
+
+.. automodule:: uniswap.token
+
+.. autoclass:: BaseToken
+   :members:
+
+.. autoclass:: ERC20Token
+   :inherited-members:
+   :members:
+
 Exceptions
 ----------
 
+.. automodule:: uniswap.exceptions
+
 .. autoexception:: InvalidToken
 
 .. autoexception:: InsufficientBalance
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,7 +28,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx_click"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.extlinks", "sphinx_click"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -38,6 +38,10 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+extlinks = {
+    "issue": ("https://github.com/shanefontaine/uniswap-python/issues/%s", "issue #"),
+}
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -60,6 +64,10 @@
     "path_to_docs": "docs",
     "use_repository_button": True,
     "use_edit_page_button": True,
+    "extra_navbar": """
+    <p>
+        Back to <a href="https://github.com/shanefontaine/uniswap-python">GitHub</a>
+    </p>""",
 }
 
 show_navbar_depth = 2

diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -0,0 +1,162 @@
+Getting started
+===============
+
+This library attempts to present a clean interface to Uniswap, but in order to use it to its full potential, you must familiarize yourself with the official Uniswap documentation:
+
+- V1: https://uniswap.org/docs/v1/
+- V2: https://uniswap.org/docs/v2/
+- V3: https://docs.uniswap.org/
+
+.. contents:: Table of contents
+    :local:
+    :depth: 3
+
+Installation
+------------
+
+You can install the latest release from PyPI, or install the latest commit directly from git:
+
+.. code:: sh
+
+    pip install uniswap-python
+
+    # or
+
+    pip install git+git://github.com/shanefontaine/uniswap-python.git
+
+
+Initializing the Uniswap class
+------------------------------
+
+If you want to trade you need to provide your address and private key. If not, you can set them to ``None``.
+
+In addition, the :class:`~uniswap.Uniswap` class takes several optional parameters, as documented in the `API Reference`.
+
+.. code:: python
+
+    from uniswap import Uniswap
+
+    address = "YOUR ADDRESS"          # or None if you're not going to make transactions
+    private_key = "YOUR PRIVATE KEY"  # or None if you're not going to make transactions
+    version = 2                       # specify which version of Uniswap to use
+    provider = "WEB3 PROVIDER URL"    # can also be set through the environment variable `PROVIDER`
+    uniswap = Uniswap(address=address, private_key=private_key, version=version, provider=provider)
+
+    # Some token addresses we'll be using later in this guide
+    eth = "0x0000000000000000000000000000000000000000"
+    bat = "0x0D8775F648430679A709E98d2b0Cb6250d2887EF"
+    dai = "0x89d24A6b4CcB1B6fAA2625fE562bDD9a23260359"
+
+
+Environment Variables
+`````````````````````
+
+The program expects an environment variables to be set in order to run the program. You can use an Infura node, since the transactions are being signed locally and broadcast as a raw transaction. The environment variable is:
+
+.. code:: sh
+
+    PROVIDER  # HTTP Provider for web3
+
+Gas pricing
+```````````
+
+To modify the gas pricing strategy you need to pass a custom `Web3` instance to the :class:`~uniswap.Uniswap` constructor. You can find details for how to configure Web3 gas strategies in their `documentation <https://web3py.readthedocs.io/en/stable/gas_price.html>`_.
+
+
+Quoting prices
+--------------
+
+.. note::
+
+    These methods assume a certain route for the swap to take, which may not be the optimal route. See :issue:`69` for details.
+
+There are two functions to retrieve the price for a given pair, one for specifying how much you get given a certain amount of the input token, and another for specifying how much you need to pay to receive a certain amount of the output token.
+
+:func:`~uniswap.Uniswap.get_price_input`
+````````````````````````````````````````
+
+Returns the cost of the given number of input tokens, priced in the output token.
+
+.. code:: python
+
+    # Returns the amount of DAI you get for 1 ETH (10^18 wei)
+    uniswap.get_price_input(eth, dai, 10**18)
+
+:func:`~uniswap.Uniswap.get_price_output`
+`````````````````````````````````````````
+
+Returns the amount of input token you need for the given amount of output tokens.
+
+.. code:: python
+
+    # Returns the amount of ETH you need to pay (in wei) to get 1000 DAI
+    uniswap.get_price_output(eth, dai, 1_000 * 10**18)
+
+
+.. note:: 
+
+    These methods return the price as an integer in the smallest unit of the token. You need to ensure that you know how many decimals the token you're trying to trade uses to get prices in the common decimal format. See :issue:`12` for details.
+
+    Decimals for common tokens:
+
+    - ETH, DAI, and BAT uses 18 decimals (as you can see in code below)
+    - WBTC uses 8 decimals
+    - USDC and USDT uses 6 decimals
+
+    You can look up the number of decimals used by a particular token by looking up the contract on Etherscan.
+
+Making trades
+-------------
+
+.. note::
+
+    The same route assumptions and need for handling decimals apply here as those mentioned in the previous section.
+
+:func:`~uniswap.Uniswap.make_trade`
+```````````````````````````````````
+
+.. code:: python
+
+    # Make a trade based on the input parameters
+    uniswap.make_trade(eth, bat, 1*10**18)
+    uniswap.make_trade(bat, eth, 1*10**18)
+    uniswap.make_trade(bat, dai, 1*10**18)
+    uniswap.make_trade(eth, bat, 1*10**18, "0x123...")
+
+:func:`~uniswap.Uniswap.make_trade_output`
+``````````````````````````````````````````
+
+.. code:: python
+
+    # Make a trade where the output qty isearch)Lknown based on the input parameters
+    uniswap.make_trade_output(eth, bat, 1*10**18) # calls _eth_to_token_swap_output
+    uniswap.make_trade_output(bat, eth, 1*10**18) # calls _token_to_eth_swap_output
+    uniswap.make_trade_output(bat, dai, 1*10**18, "0x123...") # calls _token_to_token_swap_output
+
+
+Pool Methods (v1 only)
+---------------------------
+
+.. code:: python
+
+    # Get the balance of ETH in an exchange contract.
+    uniswap.get_ex_eth_balance(bat)
+
+    # Get the balance of a token in an exchange contract.
+    uniswap.get_ex_token_balance(bat)
+
+    # Get the exchange rate of token/ETH
+    uniswap.get_exchange_rate(bat)
+
+
+Liquidity Methods (v1 only)
+---------------------------
+
+.. code:: python
+
+    # Add liquidity to the pool.
+    uniswap.add_liquidity(bat, 1*10**18)
+
+    # Remove liquidity from the pool.
+    uniswap.remove_liquidity(bat, 1*10**18)
+