dexsnake 0.1.0__tar.gz

dexsnake-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Leevi Kerkelä
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dexsnake-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: dexsnake
+Version: 0.1.0
+Summary: A Python package for trading on decentralized exchanges like Uniswap.
+Author-email: Leevi Kerkelä <leevi.kerkela@protonmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kerkelae/dexsnake
+Project-URL: Documentation, https://dexsnake.readthedocs.io/
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: web3<8,>=7
+Dynamic: license-file
+
+Dexsnake
+========
+
+Dexsnake is a lightweight Python package that makes it easy to make trades on
+decentralized exchanges (DEXs) like `Uniswap <https://uniswap.org/>`_. The package is
+designed for Python developers, quants, data scientists, algorithmic traders, and others
+who are used to working in Python but may not have in-depth knowledge about blockchains
+and decentralized apps. The code is organized to closely follow the structure of the
+smart contracts, ensuring that by using Dexsnake, users also gain an understanding of
+the underlying protocols.
+
+Installation
+############
+
+.. note::
+
+   Dexsnake is under active development. Its API may change before version 1.0.
+   Review transaction parameters carefully before trading with real funds.
+
+The most recent release can be installed with `pip <https://pip.pypa.io/>`_:
+
+.. code-block::
+
+   pip install dexsnake
+
+The development version can be installed from GitHub:
+
+.. code-block::
+
+   pip install git+https://github.com/kerkelae/dexsnake.git
+
+Contributing
+############
+
+See the `Contributing guide <https://dexsnake.readthedocs.io/en/latest/contributing.html>`_
+for development setup and tests.

dexsnake-0.1.0/README.rst

@@ -0,0 +1,36 @@
+Dexsnake
+========
+
+Dexsnake is a lightweight Python package that makes it easy to make trades on
+decentralized exchanges (DEXs) like `Uniswap <https://uniswap.org/>`_. The package is
+designed for Python developers, quants, data scientists, algorithmic traders, and others
+who are used to working in Python but may not have in-depth knowledge about blockchains
+and decentralized apps. The code is organized to closely follow the structure of the
+smart contracts, ensuring that by using Dexsnake, users also gain an understanding of
+the underlying protocols.
+
+Installation
+############
+
+.. note::
+
+   Dexsnake is under active development. Its API may change before version 1.0.
+   Review transaction parameters carefully before trading with real funds.
+
+The most recent release can be installed with `pip <https://pip.pypa.io/>`_:
+
+.. code-block::
+
+   pip install dexsnake
+
+The development version can be installed from GitHub:
+
+.. code-block::
+
+   pip install git+https://github.com/kerkelae/dexsnake.git
+
+Contributing
+############
+
+See the `Contributing guide <https://dexsnake.readthedocs.io/en/latest/contributing.html>`_
+for development setup and tests.

dexsnake-0.1.0/dexsnake/__init__.py

@@ -0,0 +1,3 @@
+from . import uniswap_v2 as uniswap_v2
+from . import uniswap_v3 as uniswap_v3
+from .erc20_token import ERC20Token as ERC20Token

dexsnake-0.1.0/dexsnake/abi/ERC20Token.json

@@ -0,0 +1,295 @@
+[
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "name",
+        "outputs": [
+            {
+                "name": "",
+                "type": "string"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "_spender",
+                "type": "address"
+            },
+            {
+                "name": "_value",
+                "type": "uint256"
+            }
+        ],
+        "name": "approve",
+        "outputs": [
+            {
+                "name": "success",
+                "type": "bool"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "totalSupply",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "_from",
+                "type": "address"
+            },
+            {
+                "name": "_to",
+                "type": "address"
+            },
+            {
+                "name": "_value",
+                "type": "uint256"
+            }
+        ],
+        "name": "transferFrom",
+        "outputs": [
+            {
+                "name": "success",
+                "type": "bool"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "decimals",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint8"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "_value",
+                "type": "uint256"
+            }
+        ],
+        "name": "burn",
+        "outputs": [
+            {
+                "name": "success",
+                "type": "bool"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [
+            {
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "name": "balanceOf",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "_from",
+                "type": "address"
+            },
+            {
+                "name": "_value",
+                "type": "uint256"
+            }
+        ],
+        "name": "burnFrom",
+        "outputs": [
+            {
+                "name": "success",
+                "type": "bool"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [],
+        "name": "symbol",
+        "outputs": [
+            {
+                "name": "",
+                "type": "string"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "_to",
+                "type": "address"
+            },
+            {
+                "name": "_value",
+                "type": "uint256"
+            }
+        ],
+        "name": "transfer",
+        "outputs": [],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "constant": false,
+        "inputs": [
+            {
+                "name": "_spender",
+                "type": "address"
+            },
+            {
+                "name": "_value",
+                "type": "uint256"
+            },
+            {
+                "name": "_extraData",
+                "type": "bytes"
+            }
+        ],
+        "name": "approveAndCall",
+        "outputs": [
+            {
+                "name": "success",
+                "type": "bool"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "constant": true,
+        "inputs": [
+            {
+                "name": "",
+                "type": "address"
+            },
+            {
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "name": "allowance",
+        "outputs": [
+            {
+                "name": "",
+                "type": "uint256"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "name": "initialSupply",
+                "type": "uint256"
+            },
+            {
+                "name": "tokenName",
+                "type": "string"
+            },
+            {
+                "name": "tokenSymbol",
+                "type": "string"
+            }
+        ],
+        "payable": false,
+        "stateMutability": "nonpayable",
+        "type": "constructor"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "name": "from",
+                "type": "address"
+            },
+            {
+                "indexed": true,
+                "name": "to",
+                "type": "address"
+            },
+            {
+                "indexed": false,
+                "name": "value",
+                "type": "uint256"
+            }
+        ],
+        "name": "Transfer",
+        "type": "event"
+    },
+    {
+        "anonymous": false,
+        "inputs": [
+            {
+                "indexed": true,
+                "name": "from",
+                "type": "address"
+            },
+            {
+                "indexed": false,
+                "name": "value",
+                "type": "uint256"
+            }
+        ],
+        "name": "Burn",
+        "type": "event"
+    }
+]

dexsnake-0.1.0/dexsnake/amounts.py

@@ -0,0 +1,23 @@
+from decimal import Decimal
+from typing import Union
+
+
+def _from_base_units(units: int, decimals: int) -> Decimal:
+    return Decimal(
+        f"{units}e-{decimals}"
+    )  # to avoid rounding large amounts to the active Decimal precision
+
+
+def _to_base_units(value: Union[Decimal, int], decimals: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, (Decimal, int)):
+        raise TypeError("Token amount must be a Decimal or integer")
+    value = Decimal(value)
+    if not value.is_finite() or value < 0:
+        raise ValueError("Token amount must be finite and non-negative")
+    numerator, denominator = value.as_integer_ratio()
+    units, remainder = divmod(numerator * 10**decimals, denominator)
+    if remainder:
+        raise ValueError(f"Token amount exceeds {decimals} decimal places")
+    if units >= 2**256:
+        raise ValueError("Token amount exceeds uint256 range")
+    return units

dexsnake-0.1.0/dexsnake/erc20_token.py

@@ -0,0 +1,184 @@
+import json
+import os
+from decimal import Decimal
+from typing import Optional
+
+from web3 import Web3
+from web3.contract import Contract
+from web3.types import TxReceipt
+
+from .amounts import _from_base_units, _to_base_units
+from .transactions import _send_transaction
+
+
+class ERC20Token:
+    def __init__(self, web3: Web3, address: str):
+        """
+        Initializes a new instance of the ``ERC20Token`` class.
+
+        For details about the ERC20 standard, see https://eips.ethereum.org/EIPS/eip-20.
+
+        :param web3: A ``Web3`` instance connected to a blockchain node.
+        :type web3: ``Web3``
+        :param address: The address of the ERC20 token contract.
+        :type address: str
+        """
+        self.web3: Web3 = web3
+        address_checksum = self.web3.to_checksum_address(address)
+        self.address: str = address_checksum
+        abi_path = os.path.join(os.path.dirname(__file__), "abi", "ERC20Token.json")
+        with open(abi_path, "r") as file:
+            self.contract: Contract = self.web3.eth.contract(
+                address=address_checksum, abi=json.load(file)
+            )
+        self._name: Optional[str] = None
+        self._symbol: Optional[str] = None
+        self._decimals: Optional[int] = None
+
+    def allowance(self, owner: str, spender: str) -> Decimal:
+        """
+        Returns the amount which ``spender`` is allowed to withdraw from ``owner``.
+
+        :param owner: The address of the token owner.
+        :type owner: str
+        :param spender: The address of the spender.
+        :type spender: str
+
+        :return: The remaining allowance of tokens.
+        :rtype: ``Decimal``
+        """
+        return _from_base_units(
+            self.contract.functions.allowance(
+                self.web3.to_checksum_address(owner),
+                self.web3.to_checksum_address(spender),
+            ).call(),
+            self.decimals,
+        )
+
+    def approve(
+        self,
+        spender: str,
+        value: Decimal,
+        private_key: str,
+        gas: Optional[int] = None,
+        gas_price: Optional[int] = None,
+    ) -> TxReceipt:
+        """
+        Approves the specified address to spend the specified amount of tokens on behalf
+        of the caller.
+
+        :param spender: The address to approve.
+        :type spender: str
+        :param value: The amount of tokens to approve.
+        :type value: ``Decimal``
+        :param private_key: The private key of the account.
+        :type private_key: str
+        :param gas: The gas limit for the transaction. If not provided, it will be
+            estimated automatically.
+        :type gas: int, optional
+        :param gas_price: The gas price for the transaction in wei. If not provided, the
+            current network gas price will be used.
+        :type gas_price: int, optional
+
+        :return: The transaction receipt.
+        :rtype: TxReceipt
+        """
+        function = self.contract.functions.approve(
+            self.web3.to_checksum_address(spender),
+            _to_base_units(value, self.decimals),
+        )
+        return _send_transaction(self.web3, function, private_key, gas, gas_price)
+
+    def balance_of(self, account: str) -> Decimal:
+        """
+        Returns the balance of the specified account.
+
+        :param account: The address of the account.
+        :type account: str
+
+        :return: The balance of the account.
+        :rtype: ``Decimal``
+        """
+        return _from_base_units(
+            self.contract.functions.balanceOf(
+                self.web3.to_checksum_address(account)
+            ).call(),
+            self.decimals,
+        )
+
+    @property
+    def decimals(self) -> int:
+        """
+        Returns the number of decimals the token uses.
+
+        :return: The number of decimals.
+        """
+        if self._decimals is None:
+            self._decimals = self.contract.functions.decimals().call()
+        return self._decimals
+
+    @property
+    def name(self) -> str:
+        """
+        Returns the name of the token.
+
+        :return: The token name.
+        """
+        if self._name is None:
+            self._name = self.contract.functions.name().call()
+        return self._name
+
+    @property
+    def symbol(self) -> str:
+        """
+        Returns the symbol of the token.
+
+        :return: The token symbol.
+        """
+        if self._symbol is None:
+            self._symbol = self.contract.functions.symbol().call()
+        return self._symbol
+
+    def total_supply(self) -> Decimal:
+        """
+        Returns the total supply of the token.
+
+        :return: Total token supply.
+        :rtype: ``Decimal``
+        """
+        return _from_base_units(
+            self.contract.functions.totalSupply().call(), self.decimals
+        )
+
+    def transfer(
+        self,
+        to: str,
+        value: Decimal,
+        private_key: str,
+        gas: Optional[int] = None,
+        gas_price: Optional[int] = None,
+    ) -> TxReceipt:
+        """
+        Transfers tokens to the specified address.
+
+        :param to: The address to transfer tokens to.
+        :type to: str
+        :param value: The amount of tokens to transfer.
+        :type value: ``Decimal``
+        :param private_key: The private key of the account.
+        :type private_key: str
+        :param gas: The gas limit for the transaction. If not provided, it will be
+            estimated automatically.
+        :type gas: int, optional
+        :param gas_price: The gas price for the transaction in wei. If not provided, the
+            current network gas price will be used.
+        :type gas_price: int, optional
+
+        :return: The transaction receipt.
+        :rtype: TxReceipt
+        """
+        function = self.contract.functions.transfer(
+            self.web3.to_checksum_address(to),
+            _to_base_units(value, self.decimals),
+        )
+        return _send_transaction(self.web3, function, private_key, gas, gas_price)

dexsnake-0.1.0/dexsnake/transactions.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+from web3 import Web3
+from web3.contract.contract import ContractFunction
+from web3.types import TxReceipt
+
+
+def _send_transaction(
+    web3: Web3,
+    function: ContractFunction,
+    private_key: str,
+    gas: Optional[int],
+    gas_price: Optional[int],
+) -> TxReceipt:
+    account = web3.eth.account.from_key(private_key)
+    if gas_price is None:
+        gas_price = web3.eth.gas_price
+    tx_params = {
+        "from": account.address,
+        "nonce": web3.eth.get_transaction_count(account.address, "pending"),
+        "gasPrice": gas_price,
+    }
+    if gas is not None:
+        tx_params["gas"] = gas
+    tx = function.build_transaction(tx_params)
+    signed_tx = account.sign_transaction(tx)
+    tx_hash = web3.eth.send_raw_transaction(signed_tx.raw_transaction)
+    receipt = web3.eth.wait_for_transaction_receipt(tx_hash)
+    if receipt["status"] == 0:
+        raise RuntimeError(f"Transaction {Web3.to_hex(tx_hash)} failed")
+    return receipt

dexsnake-0.1.0/dexsnake/uniswap_v2/__init__.py

@@ -0,0 +1,3 @@
+from .factory import UniswapV2Factory as UniswapV2Factory
+from .pair import UniswapV2Pair as UniswapV2Pair
+from .router import UniswapV2Router as UniswapV2Router