charli3_dendrite 0.2.0.dev116__tar.gz

charli3_dendrite-0.2.0.dev116/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Charli3-Official and SteelSwap
+
+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.

charli3_dendrite-0.2.0.dev116/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.1
+Name: charli3_dendrite
+Version: 0.2.0.dev116
+Summary: 
+Author: Elder Millenial
+Author-email: eldermillenial@protonmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: blockfrost-python (>=0.5.3,<0.6.0)
+Requires-Dist: psycopg[binary,pool] (>=3.1.13,<4.0.0)
+Requires-Dist: pycardano (==0.11.1)
+Requires-Dist: pydantic (>=2.5.2,<3.0.0)
+Requires-Dist: python-dotenv (==0.21.1)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <h1 align="center">Charli3 Dendrite</h1>
+    <p align="center">Python SDK for interacting with Cardano DEXs</p>
+    <p>
+        <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python version">
+        <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
+        <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome">
+    </p>
+</div>
+
+## Overview
+
+Charli3 Dendrite is a powerful Python SDK designed for seamless interaction with multiple Decentralized Exchanges (DEXs) on the Cardano blockchain. It provides a unified interface for developers to access various DEX functionalities, simplifying the process of building applications in the Cardano ecosystem.
+
+## Key Features
+
+- 🔄 Multi-DEX Support: Integrate with Minswap, MuesliSwap, Spectrum, SundaeSwap, VyFi, GeniusYield, Axo, and WingRiders
+- 💧 Liquidity Pool Data: Fetch and analyze pool information across different DEXs
+- 💱 Swap Operations: Execute token swaps with ease
+- 🧩 Flexible Asset Handling: Manage various asset types and pool states efficiently
+- 🔗 On-chain Data Integration: Connect with Blockfrost or custom data providers
+- 🛠 Extensible Architecture: Easily add support for new DEXs and features
+
+
+## Quick Start
+
+### Installation
+
+```bash
+# Using pip
+pip install charli3_dendrite
+
+# Using Poetry
+poetry add charli3_dendrite
+```
+
+## Supported DEXs
+Charli3 Dendrite currently supports the following Cardano DEXs:
+
+- Minswap
+- MuesliSwap
+- Spectrum
+- SundaeSwap
+- VyFi
+- WingRiders
+- GeniusYield
+- Axo
+
+## Upcoming DEXs
+
+- CardanoSwaps
+- Metadex
+- CSwap
+
+## Not Supported
+
+- TeddySwap
+- Cerra
+- SaturnSwap
+- Splash
+
+Each DEX is implemented as a separate module within the `charli3 dendrite.dexs.amm` package.
+## Core Components
+### AbstractPoolState
+The `AbstractPoolState` class in `amm_base.py` provides the base implementation for AMM (Automated Market Maker) pool states. It includes methods for:
+
+- Extracting pool information
+- Handling swap operations
+- Calculating prices and TVL (Total Value Locked)
+
+### AbstractPairState
+The `AbstractPairState` class in `base.py` defines the interface for all pair states (both AMM and orderbook-based). It includes abstract methods that must be implemented by specific DEX classes.
+### Assets
+The `Assets` class in `models.py` represents a collection of assets (tokens) and their quantities. It provides utility methods for working with asset collections, including addition and subtraction operations.
+## Configuration
+Charli3 Dendrite can be configured using environment variables or a `.env` file. See `sample.env` for an example of the configuration options.
+
+### Data Provider Configuration
+
+Charli3 Dendrite supports multiple data providers to fetch on-chain data. Currently, it supports Blockfrost and DBSync, with plans to add Ogmios and Kupo in the future.
+
+#### Blockfrost Configuration
+
+Blockfrost is the default data provider for Charli3 Dendrite. To use Blockfrost, you need to set up your API key in the environment variables or `.env` file:
+```
+PROJECT_ID="your-blockfrost-project-id"
+NETWORK="mainnet"  # or "testnet" for the Cardano testnet
+```
+#### DBSync Configuration
+Charli3 Dendrite also supports using a DBSync instance as a data provider. To configure DBSync, set the following environment variables:
+```bash
+DBSYNC_HOST="your-dbsync-host"
+DBSYNC_PORT="your-dbsync-port"
+DBSYNC_DB_NAME="your-dbsync-database-name"
+DBSYNC_USER="your-dbsync-username"
+DBSYNC_PASS="your-dbsync-password"
+```
+#### Future Plans: Ogmios and Kupo
+We are planning to add support for Ogmios and Kupo as additional data providers in future releases. These will offer alternative ways to interact with the Cardano blockchain and may provide performance improvements or additional features.
+Stay tuned for updates on the integration of these providers. Once implemented, they will be configurable in a similar manner to the existing providers.
+### Wallet Configuration
+Charli3 Dendrite supports wallet integration for performing transactions. You can configure a wallet using a mnemonic phrase:
+```bash
+WALLET_MNEMONIC="your wallet mnemonic phrase"
+```
+## Development
+To set up the development environment:
+
+1. Clone the repository
+2. Install dependencies: `poetry install`
+3. Set up pre-commit hooks: `pre-commit install`
+
+## Running Tests
+```bash
+poetry run pytest --benchmark-disable -v --slow -n auto
+```
+For parallel test execution:
+```bash
+poetry run pytest -n auto
+```
+## Contributing
+Contributions to Charli3 Dendrite are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines on how to contribute to the project.
+

charli3_dendrite-0.2.0.dev116/README.md

@@ -0,0 +1,122 @@
+<div align="center">
+    <h1 align="center">Charli3 Dendrite</h1>
+    <p align="center">Python SDK for interacting with Cardano DEXs</p>
+    <p>
+        <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python version">
+        <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
+        <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome">
+    </p>
+</div>
+
+## Overview
+
+Charli3 Dendrite is a powerful Python SDK designed for seamless interaction with multiple Decentralized Exchanges (DEXs) on the Cardano blockchain. It provides a unified interface for developers to access various DEX functionalities, simplifying the process of building applications in the Cardano ecosystem.
+
+## Key Features
+
+- 🔄 Multi-DEX Support: Integrate with Minswap, MuesliSwap, Spectrum, SundaeSwap, VyFi, GeniusYield, Axo, and WingRiders
+- 💧 Liquidity Pool Data: Fetch and analyze pool information across different DEXs
+- 💱 Swap Operations: Execute token swaps with ease
+- 🧩 Flexible Asset Handling: Manage various asset types and pool states efficiently
+- 🔗 On-chain Data Integration: Connect with Blockfrost or custom data providers
+- 🛠 Extensible Architecture: Easily add support for new DEXs and features
+
+
+## Quick Start
+
+### Installation
+
+```bash
+# Using pip
+pip install charli3_dendrite
+
+# Using Poetry
+poetry add charli3_dendrite
+```
+
+## Supported DEXs
+Charli3 Dendrite currently supports the following Cardano DEXs:
+
+- Minswap
+- MuesliSwap
+- Spectrum
+- SundaeSwap
+- VyFi
+- WingRiders
+- GeniusYield
+- Axo
+
+## Upcoming DEXs
+
+- CardanoSwaps
+- Metadex
+- CSwap
+
+## Not Supported
+
+- TeddySwap
+- Cerra
+- SaturnSwap
+- Splash
+
+Each DEX is implemented as a separate module within the `charli3 dendrite.dexs.amm` package.
+## Core Components
+### AbstractPoolState
+The `AbstractPoolState` class in `amm_base.py` provides the base implementation for AMM (Automated Market Maker) pool states. It includes methods for:
+
+- Extracting pool information
+- Handling swap operations
+- Calculating prices and TVL (Total Value Locked)
+
+### AbstractPairState
+The `AbstractPairState` class in `base.py` defines the interface for all pair states (both AMM and orderbook-based). It includes abstract methods that must be implemented by specific DEX classes.
+### Assets
+The `Assets` class in `models.py` represents a collection of assets (tokens) and their quantities. It provides utility methods for working with asset collections, including addition and subtraction operations.
+## Configuration
+Charli3 Dendrite can be configured using environment variables or a `.env` file. See `sample.env` for an example of the configuration options.
+
+### Data Provider Configuration
+
+Charli3 Dendrite supports multiple data providers to fetch on-chain data. Currently, it supports Blockfrost and DBSync, with plans to add Ogmios and Kupo in the future.
+
+#### Blockfrost Configuration
+
+Blockfrost is the default data provider for Charli3 Dendrite. To use Blockfrost, you need to set up your API key in the environment variables or `.env` file:
+```
+PROJECT_ID="your-blockfrost-project-id"
+NETWORK="mainnet"  # or "testnet" for the Cardano testnet
+```
+#### DBSync Configuration
+Charli3 Dendrite also supports using a DBSync instance as a data provider. To configure DBSync, set the following environment variables:
+```bash
+DBSYNC_HOST="your-dbsync-host"
+DBSYNC_PORT="your-dbsync-port"
+DBSYNC_DB_NAME="your-dbsync-database-name"
+DBSYNC_USER="your-dbsync-username"
+DBSYNC_PASS="your-dbsync-password"
+```
+#### Future Plans: Ogmios and Kupo
+We are planning to add support for Ogmios and Kupo as additional data providers in future releases. These will offer alternative ways to interact with the Cardano blockchain and may provide performance improvements or additional features.
+Stay tuned for updates on the integration of these providers. Once implemented, they will be configurable in a similar manner to the existing providers.
+### Wallet Configuration
+Charli3 Dendrite supports wallet integration for performing transactions. You can configure a wallet using a mnemonic phrase:
+```bash
+WALLET_MNEMONIC="your wallet mnemonic phrase"
+```
+## Development
+To set up the development environment:
+
+1. Clone the repository
+2. Install dependencies: `poetry install`
+3. Set up pre-commit hooks: `pre-commit install`
+
+## Running Tests
+```bash
+poetry run pytest --benchmark-disable -v --slow -n auto
+```
+For parallel test execution:
+```bash
+poetry run pytest -n auto
+```
+## Contributing
+Contributions to Charli3 Dendrite are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines on how to contribute to the project.

charli3_dendrite-0.2.0.dev116/pyproject.toml

@@ -0,0 +1,41 @@
+[tool.poetry]
+name = "charli3_dendrite"
+version = "0.2.0-dev116"
+description = ""
+authors = ["Elder Millenial <eldermillenial@protonmail.com>"]
+readme = "README.md"
+packages = [{include = "charli3_dendrite", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+requests = "^2.31.0"
+pydantic = "^2.5.2"
+psycopg = {extras = ["binary", "pool"], version = "^3.1.13"}
+python-dotenv = "0.21.1"
+pycardano = "0.11.1"
+blockfrost-python = "^0.5.3"
+
+
+[tool.poetry.group.dev.dependencies]
+black = "^23.11.0"
+ruff = "^0.1.6"
+pre-commit = "^3.5.0"
+bump2version = "^1.0.1"
+isort = "^5.13.2"
+flake8 = "^6.1.0"
+mypy = "^1.7.1"
+pytest = "^7.4.3"
+pytest-benchmark = "^4.0.0"
+pytest-dependency = "^0.5.1"
+pytest-xdist = "^3.6.1"
+
+
+[tool.poetry.group.devs.dependencies]
+pytest-subtests = "^0.11.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.isort]
+profile = "black"

charli3_dendrite-0.2.0.dev116/src/charli3_dendrite/__init__.py

@@ -0,0 +1,18 @@
+# noqa
+from charli3_dendrite.dexs.amm.minswap import MinswapCPPState
+from charli3_dendrite.dexs.amm.minswap import MinswapDJEDiUSDStableState
+from charli3_dendrite.dexs.amm.minswap import MinswapDJEDUSDCStableState
+from charli3_dendrite.dexs.amm.minswap import MinswapDJEDUSDMStableState
+from charli3_dendrite.dexs.amm.minswap import MinswapV2CPPState
+from charli3_dendrite.dexs.amm.muesli import MuesliSwapCLPState
+from charli3_dendrite.dexs.amm.muesli import MuesliSwapCPPState
+from charli3_dendrite.dexs.amm.spectrum import SpectrumCPPState
+from charli3_dendrite.dexs.amm.sundae import SundaeSwapCPPState
+from charli3_dendrite.dexs.amm.sundae import SundaeSwapV3CPPState
+from charli3_dendrite.dexs.amm.vyfi import VyFiCPPState
+from charli3_dendrite.dexs.amm.wingriders import WingRidersCPPState
+from charli3_dendrite.dexs.amm.wingriders import WingRidersSSPState
+from charli3_dendrite.dexs.ob.axo import AxoOBMarketState
+from charli3_dendrite.dexs.ob.geniusyield import GeniusYieldOrderBook
+from charli3_dendrite.dexs.ob.geniusyield import GeniusYieldOrderState
+from charli3_dendrite.utility import Assets

charli3_dendrite-0.2.0.dev116/src/charli3_dendrite/backend/__init__.py

@@ -0,0 +1,97 @@
+"""Backend Management Module for Charli3 Dendrite.
+
+This module provides a centralized system for managing the backend used throughout
+the Charli3 Dendrite application. It includes functions to get and set the global backend,
+as well as to set a default backend based on environment variables.
+
+The module uses a global variable to store the current backend instance, which
+can be accessed and modified using the provided functions. This approach allows
+for easy switching between different backend implementations and provides a
+convenient way to set up a default backend.
+
+Typical usage:
+    from charli3_dendrite.backends import get_backend, set_backend
+    from charli3_dendrite.backend.custom_backend import CustomBackend
+
+    # Get the current backend (initializes a default if not set)
+    backend = get_backend()
+
+    # Set a custom backend
+    set_backend(CustomBackend())
+
+Note: This module relies on environment variables for setting up the default backend.
+Ensure that the necessary environment variables are set before using this module.
+"""
+
+import os
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from charli3_dendrite.backend.backend_base import AbstractBackend
+from charli3_dendrite.backend.dbsync import DbsyncBackend
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Global variable to store the current backend instance
+BACKEND: Optional[AbstractBackend] = None
+
+
+def get_backend() -> AbstractBackend:
+    """Retrieve the current backend instance.
+
+    If no backend has been set, this function attempts to set a default backend
+    based on environment variables. If no default can be set, it raises a ValueError.
+
+    Returns:
+        AbstractBackend: The current backend instance.
+
+    Raises:
+        ValueError: If no backend has been set and no default can be determined.
+    """
+    if BACKEND is None:
+        set_default_backend()
+    if BACKEND is None:
+        raise ValueError("Backend has not been set. Call set_backend() first.")
+    return BACKEND
+
+
+def set_backend(backend: AbstractBackend) -> None:
+    """Set the global backend instance.
+
+    Args:
+        backend (AbstractBackend): The backend instance to set as the global backend.
+    """
+    global BACKEND  # noqa: PLW0603
+    BACKEND = backend
+
+
+def set_default_backend() -> None:
+    """Attempt to set a default backend based on environment variables.
+
+    This function checks for the presence of specific environment variables
+    to determine which backend to use as the default. Currently, it only
+    checks for DBSync-related variables, but can be extended to support
+    other backend types in the future.
+    """
+    # Check for DBSync environment variables
+    dbsync_vars = [
+        "DBSYNC_USER",
+        "DBSYNC_PASS",
+        "DBSYNC_HOST",
+        "DBSYNC_PORT",
+        "DBSYNC_DB_NAME",
+    ]
+    if all(env_var in os.environ for env_var in dbsync_vars):
+        set_backend(DbsyncBackend())
+
+    """ TODO: Add checks for other backend types here as needed
+    For example:
+    elif all(env_var in os.environ for env_var in other_backend_vars):
+        set_backend(OtherBackend())
+    """
+
+
+# Optional: Initialize the backend when the module is imported
+set_default_backend()

charli3_dendrite-0.2.0.dev116/src/charli3_dendrite/backend/backend_base.py

@@ -0,0 +1,186 @@
+"""Abstract base class for Cardano blockchain backend implementations."""
+
+from abc import ABC
+from abc import abstractmethod
+from datetime import datetime
+
+from pycardano import Address
+
+from charli3_dendrite.dataclasses.models import BlockList
+from charli3_dendrite.dataclasses.models import PoolStateList
+from charli3_dendrite.dataclasses.models import ScriptReference
+from charli3_dendrite.dataclasses.models import SwapTransactionList
+
+
+class AbstractBackend(ABC):
+    """Abstract base class for Cardano blockchain backend implementations.
+
+    This class defines the interface for interacting with various Cardano blockchain
+    data sources such as db-sync, Ogmios, or Kupo.
+    """
+
+    @abstractmethod
+    def get_pool_utxos(  # noqa: PLR0913
+        self,
+        assets: list[str] | None = None,
+        addresses: list[str] | None = None,
+        limit: int = 1000,
+        page: int = 0,
+        historical: bool = True,
+    ) -> PoolStateList:
+        """Get UTXOs for specific assets or addresses.
+
+        Args:
+            assets (Optional[List[str]]): List of asset IDs to filter by.
+            addresses (Optional[List[str]]): List of addresses to filter by.
+            limit (int): Maximum number of results to return.
+            page (int): Page number for pagination.
+            historical (bool): Whether to include historical data.
+
+        Returns:
+            PoolStateList: List of pool state objects.
+        """
+        pass
+
+    @abstractmethod
+    def get_pool_in_tx(
+        self,
+        tx_hash: str,
+        assets: list[str] | None = None,
+        addresses: list[str] | None = None,
+    ) -> PoolStateList:
+        """Get pool state for a specific transaction.
+
+        Args:
+            tx_hash (str): The transaction hash to query.
+            assets (Optional[List[str]]): List of asset IDs to filter by.
+            addresses (Optional[List[str]]): List of addresses to filter by.
+
+        Returns:
+            PoolStateList: List of pool state objects for the transaction.
+        """
+        pass
+
+    @abstractmethod
+    def last_block(self, last_n_blocks: int = 2) -> BlockList:
+        """Get information about the last n blocks.
+
+        Args:
+            last_n_blocks (int): Number of recent blocks to retrieve.
+
+        Returns:
+            BlockList: List of recent block information.
+        """
+        pass
+
+    @abstractmethod
+    def get_pool_utxos_in_block(self, block_no: int) -> PoolStateList:
+        """Get pool UTXOs for a specific block.
+
+        Args:
+            block_no (int): The block number to query.
+
+        Returns:
+            PoolStateList: List of pool state objects for the block.
+        """
+        pass
+
+    @abstractmethod
+    def get_script_from_address(self, address: Address) -> ScriptReference:
+        """Get script reference for a given address.
+
+        Args:
+            address (Address): The address to query.
+
+        Returns:
+            ScriptReference: Script reference for the address.
+        """
+        pass
+
+    @abstractmethod
+    def get_historical_order_utxos(
+        self,
+        stake_addresses: list[str],
+        after_time: datetime | int | None = None,
+        limit: int = 1000,
+        page: int = 0,
+    ) -> SwapTransactionList:
+        """Get historical order UTXOs for given stake addresses.
+
+        Args:
+            stake_addresses (List[str]): List of stake addresses to query.
+            after_time (Optional[Union[datetime, int]]): Filter results after this time.
+            limit (int): Maximum number of results to return.
+            page (int): Page number for pagination.
+
+        Returns:
+            SwapTransactionList: List of swap transaction objects.
+        """
+        pass
+
+    @abstractmethod
+    def get_order_utxos_by_block_or_tx(  # noqa: PLR0913
+        self,
+        stake_addresses: list[str],
+        out_tx_hash: list[str] | None = None,
+        in_tx_hash: list[str] | None = None,
+        block_no: int | None = None,
+        after_block: int | None = None,
+        limit: int = 1000,
+        page: int = 0,
+    ) -> SwapTransactionList:
+        """Get order UTXOs by block or transaction.
+
+        Args:
+            stake_addresses (List[str]): List of stake addresses to query.
+            out_tx_hash (Optional[List[str]]): List of transaction hashes to filter by.
+            in_tx_hash: list of input transaction hashes to filter by.
+            block_no (Optional[int]): Specific block number to query.
+            after_block (Optional[int]): Filter results after this block number.
+            limit (int): Maximum number of results to return.
+            page (int): Page number for pagination.
+
+        Returns:
+            SwapTransactionList: List of swap transaction objects.
+        """
+        pass
+
+    @abstractmethod
+    def get_cancel_utxos(  # noqa: PLR0913
+        self,
+        stake_addresses: list[str],
+        block_no: int | None = None,
+        after_time: datetime | int | None = None,
+        limit: int = 1000,
+        page: int = 0,
+    ) -> SwapTransactionList:
+        """Get cancelled order UTXOs.
+
+        Args:
+            stake_addresses (List[str]): List of stake addresses to query.
+            block_no (Optional[int]): Specific block number to query.
+            after_time (Optional[Union[datetime, int]]): Filter results after this time.
+            limit (int): Maximum number of results to return.
+            page (int): Page number for pagination.
+
+        Returns:
+            SwapTransactionList: List of swap transaction objects for cancelled orders.
+        """
+        pass
+
+    @abstractmethod
+    def get_datum_from_address(
+        self,
+        address: str,
+        asset: str | None = None,
+    ) -> str | None:
+        """Get datum from a given address.
+
+        Args:
+            address: The address to query.
+            asset: Assets required to be in the UTxO.
+
+        Returns:
+            The datum associated with the address, if any.
+        """
+        pass