charli3_dendrite 1.1.0.dev1__tar.gz → 1.1.1.dev0__tar.gz

charli3_dendrite-1.1.1.dev0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.1
+Name: charli3_dendrite
+Version: 1.1.1.dev0
+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: ogmios (==1.1.1)
+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 DB-sync, BlockFrost, and Ogmios/Kupo
+- 🛠 Extensible Architecture: Easily add support for new DEXs and features
+
+
+## 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
+
+### Not Yet Implemented
+
+- CardanoSwaps
+- Metadex
+- CSwap
+- TeddySwap
+- Cerra
+- SaturnSwap
+- Splash
+
+Each DEX is implemented as a separate module within the `charli3_dendrite.dexs.amm` package.
+
+## Configuration
+Charli3 Dendrite can be configured using environment variables or a `.env` file. See `sample.env` for an example of the configuration options.
+
+### Backend Configuration
+
+Charli3 Dendrite supports multiple backend options for interacting with the Cardano blockchain:
+
+#### DBSync Configuration
+
+To use a DBSync instance as the blockchain connection, 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"
+```
+
+#### BlockFrost Configuration
+
+To use BlockFrost as the backend, set the following environment variables:
+
+```bash
+BLOCKFROST_PROJECT_ID="your-blockfrost-project-id"
+CARDANO_NETWORK="mainnet"  # or "testnet" for the Cardano testnet
+```
+
+#### Ogmios/Kupo Configuration
+
+To use Ogmios and Kupo as the backend, set the following environment variables:
+
+```bash
+OGMIOS_URL="ws://your-ogmios-url:port"
+KUPO_URL="http://your-kupo-url:port"
+CARDANO_NETWORK="mainnet"  # or "testnet" for the Cardano testnet
+```
+
+The backend will be automatically selected based on the available environment variables. If multiple backend configurations are present, the priority order is: DBSync, BlockFrost, Ogmios/Kupo.
+
+### Backend Limitations
+
+While Charli3 Dendrite supports multiple backends, it's important to note that the BlockFrost and Ogmios/Kupo backends have some limitations compared to the DBSync backend:
+
+- **BlockFrost Backend**: Due to limitations in the BlockFrost API, the following methods are not implemented:
+  - `get_historical_order_utxos`
+  - `get_order_utxos_by_block_or_tx`
+  - `get_cancel_utxos`
+  - `get_axo_target`
+
+- **Ogmios/Kupo Backend**: The Ogmios/Kupo backend also has limitations due to the nature of these services:
+  - `get_historical_order_utxos`
+  - `get_order_utxos_by_block_or_tx`
+  - `get_cancel_utxos`
+
+These methods will raise a `NotImplementedError` when called using the BlockFrost or Ogmios/Kupo backends. If your application requires these functionalities, consider using the DBSync backend.
+
+## Usage
+
+### Retrieving Orders and Pool Data
+
+To retrieve orders and pool data, first configure the global backend:
+
+```python
+from charli3_dendrite.backend import set_backend, get_backend
+from charli3_dendrite.backend.dbsync import DbsyncBackend
+from charli3_dendrite.backend.blockfrost import BlockFrostBackend
+from charli3_dendrite.backend.ogmios_kupo import OgmiosKupoBackend
+from pycardano import Network
+
+# Choose one of the following backends:
+# set_backend(DbsyncBackend())
+# set_backend(BlockFrostBackend("your-project-id"))
+set_backend(OgmiosKupoBackend("ws://ogmios-url:port", "http://kupo-url:port", Network.MAINNET))
+
+backend = get_backend()
+```
+
+The `AbstractBackend` interface offers methods for interacting with the Cardano blockchain, regardless of the underlying data source. This abstraction allows seamless switching between different backends without changing your application code.
+
+To retrieve pool information, use the `pool_selector` method provided by each DEX's state class:
+
+```python
+from charli3_dendrite import VyFiCPPState
+
+selector = VyFiCPPState.pool_selector()
+result = backend.get_pool_utxos(
+    limit=100000,
+    historical=False,
+    **selector.model_dump(),
+)
+```
+To process and parse the retrieved results (`list[PoolStateInfo]`), the following approach can be utilized:
+```python
+pool_data = {}
+total_tvl = 0
+for pool in result:
+    d = dex.model_validate(pool.model_dump())
+    try:
+        logger.info("Get TVL %s", d.tvl)
+        logger.info("Price %s", d.price)
+        logger.info("Token name of asset A: %s", d.unit_a)
+        logger.info("Token name of asset B: %s", d.unit_b)
+    except NoAssetsError:
+        pass
+    except InvalidLPError:
+        pass
+    except InvalidPoolError:
+        pass
+    except Exception as e:
+        logger.debug(f"{dex.__name__}: {e}")
+```
+This approach is applicable across all supported DEXs. For example, the following list of AbstractPoolState subclasses can be defined to support various DEX states:
+```python
+DEXS: list[AbstractPoolState] = [
+    GeniusYieldOrderState,
+    MinswapCPPState,
+    MinswapV2CPPState,
+    MinswapDJEDiUSDStableState,
+    MinswapDJEDUSDCStableState,
+    MinswapDJEDUSDMStableState,
+    MuesliSwapCPPState,
+    SpectrumCPPState,
+    SundaeSwapCPPState,
+    SundaeSwapV3CPPState,
+    VyFiCPPState,
+    WingRidersCPPState,
+    WingRidersSSPState,
+]
+```
+## 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
+```
+
+## 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-1.1.1.dev0/README.md

@@ -0,0 +1,202 @@
+<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 DB-sync, BlockFrost, and Ogmios/Kupo
+- 🛠 Extensible Architecture: Easily add support for new DEXs and features
+
+
+## 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
+
+### Not Yet Implemented
+
+- CardanoSwaps
+- Metadex
+- CSwap
+- TeddySwap
+- Cerra
+- SaturnSwap
+- Splash
+
+Each DEX is implemented as a separate module within the `charli3_dendrite.dexs.amm` package.
+
+## Configuration
+Charli3 Dendrite can be configured using environment variables or a `.env` file. See `sample.env` for an example of the configuration options.
+
+### Backend Configuration
+
+Charli3 Dendrite supports multiple backend options for interacting with the Cardano blockchain:
+
+#### DBSync Configuration
+
+To use a DBSync instance as the blockchain connection, 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"
+```
+
+#### BlockFrost Configuration
+
+To use BlockFrost as the backend, set the following environment variables:
+
+```bash
+BLOCKFROST_PROJECT_ID="your-blockfrost-project-id"
+CARDANO_NETWORK="mainnet"  # or "testnet" for the Cardano testnet
+```
+
+#### Ogmios/Kupo Configuration
+
+To use Ogmios and Kupo as the backend, set the following environment variables:
+
+```bash
+OGMIOS_URL="ws://your-ogmios-url:port"
+KUPO_URL="http://your-kupo-url:port"
+CARDANO_NETWORK="mainnet"  # or "testnet" for the Cardano testnet
+```
+
+The backend will be automatically selected based on the available environment variables. If multiple backend configurations are present, the priority order is: DBSync, BlockFrost, Ogmios/Kupo.
+
+### Backend Limitations
+
+While Charli3 Dendrite supports multiple backends, it's important to note that the BlockFrost and Ogmios/Kupo backends have some limitations compared to the DBSync backend:
+
+- **BlockFrost Backend**: Due to limitations in the BlockFrost API, the following methods are not implemented:
+  - `get_historical_order_utxos`
+  - `get_order_utxos_by_block_or_tx`
+  - `get_cancel_utxos`
+  - `get_axo_target`
+
+- **Ogmios/Kupo Backend**: The Ogmios/Kupo backend also has limitations due to the nature of these services:
+  - `get_historical_order_utxos`
+  - `get_order_utxos_by_block_or_tx`
+  - `get_cancel_utxos`
+
+These methods will raise a `NotImplementedError` when called using the BlockFrost or Ogmios/Kupo backends. If your application requires these functionalities, consider using the DBSync backend.
+
+## Usage
+
+### Retrieving Orders and Pool Data
+
+To retrieve orders and pool data, first configure the global backend:
+
+```python
+from charli3_dendrite.backend import set_backend, get_backend
+from charli3_dendrite.backend.dbsync import DbsyncBackend
+from charli3_dendrite.backend.blockfrost import BlockFrostBackend
+from charli3_dendrite.backend.ogmios_kupo import OgmiosKupoBackend
+from pycardano import Network
+
+# Choose one of the following backends:
+# set_backend(DbsyncBackend())
+# set_backend(BlockFrostBackend("your-project-id"))
+set_backend(OgmiosKupoBackend("ws://ogmios-url:port", "http://kupo-url:port", Network.MAINNET))
+
+backend = get_backend()
+```
+
+The `AbstractBackend` interface offers methods for interacting with the Cardano blockchain, regardless of the underlying data source. This abstraction allows seamless switching between different backends without changing your application code.
+
+To retrieve pool information, use the `pool_selector` method provided by each DEX's state class:
+
+```python
+from charli3_dendrite import VyFiCPPState
+
+selector = VyFiCPPState.pool_selector()
+result = backend.get_pool_utxos(
+    limit=100000,
+    historical=False,
+    **selector.model_dump(),
+)
+```
+To process and parse the retrieved results (`list[PoolStateInfo]`), the following approach can be utilized:
+```python
+pool_data = {}
+total_tvl = 0
+for pool in result:
+    d = dex.model_validate(pool.model_dump())
+    try:
+        logger.info("Get TVL %s", d.tvl)
+        logger.info("Price %s", d.price)
+        logger.info("Token name of asset A: %s", d.unit_a)
+        logger.info("Token name of asset B: %s", d.unit_b)
+    except NoAssetsError:
+        pass
+    except InvalidLPError:
+        pass
+    except InvalidPoolError:
+        pass
+    except Exception as e:
+        logger.debug(f"{dex.__name__}: {e}")
+```
+This approach is applicable across all supported DEXs. For example, the following list of AbstractPoolState subclasses can be defined to support various DEX states:
+```python
+DEXS: list[AbstractPoolState] = [
+    GeniusYieldOrderState,
+    MinswapCPPState,
+    MinswapV2CPPState,
+    MinswapDJEDiUSDStableState,
+    MinswapDJEDUSDCStableState,
+    MinswapDJEDUSDMStableState,
+    MuesliSwapCPPState,
+    SpectrumCPPState,
+    SundaeSwapCPPState,
+    SundaeSwapV3CPPState,
+    VyFiCPPState,
+    WingRidersCPPState,
+    WingRidersSSPState,
+]
+```
+## 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
+```
+
+## 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-1.1.0.dev1 → charli3_dendrite-1.1.1.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "charli3_dendrite"
-version = "1.1.0-dev1"
+version = "1.1.1-dev0"
 description = ""
 authors = ["Elder Millenial <eldermillenial@protonmail.com>"]
 readme = "README.md"
@@ -14,6 +14,7 @@ psycopg = {extras = ["binary", "pool"], version = "^3.1.13"}
 python-dotenv = "0.21.1"
 pycardano = "0.11.1"
 blockfrost-python = "^0.5.3"
+ogmios = "1.1.1"
 
 
 [tool.poetry.group.dev.dependencies]
@@ -28,6 +29,9 @@ pytest = "^7.4.3"
 pytest-benchmark = "^4.0.0"
 pytest-dependency = "^0.5.1"
 pytest-xdist = "^3.6.1"
+mkdocs = "^1.6.0"
+mkdocs-material = "^9.5.32"
+mkdocstrings = {extras = ["python"], version = "^0.25.2"}
 
 
 [tool.poetry.group.devs.dependencies]
@@ -39,3 +43,10 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.isort]
 profile = "black"
+
+[tool.mypy]
+plugins = [ "pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["pycardano","pycardano.*", "dotenv", "nox"]
+ignore_missing_imports = true

{charli3_dendrite-1.1.0.dev1 → charli3_dendrite-1.1.1.dev0}/src/charli3_dendrite/backend/__init__.py

@@ -1,8 +1,8 @@
 """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 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
@@ -23,13 +23,17 @@ Note: This module relies on environment variables for setting up the default bac
 Ensure that the necessary environment variables are set before using this module.
 """
 
+import logging
 import os
 from typing import Optional
 
-from dotenv import load_dotenv
+from dotenv import load_dotenv  # type: ignore
+from pycardano import Network  # type: ignore
 
 from charli3_dendrite.backend.backend_base import AbstractBackend
+from charli3_dendrite.backend.blockfrost import BlockFrostBackend
 from charli3_dendrite.backend.dbsync import DbsyncBackend
+from charli3_dendrite.backend.ogmios_kupo import OgmiosKupoBackend
 
 # Load environment variables from .env file
 load_dotenv()
@@ -71,9 +75,8 @@ 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.
+    to determine which backend to use as the default. It checks for DBSync-related
+    variables first, then for Blockfrost, and finally for Ogmios and Kupo variables.
     """
     # Check for DBSync environment variables
     dbsync_vars = [
@@ -85,13 +88,41 @@ def set_default_backend() -> None:
     ]
     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
+        return
+
+    # Check for Blockfrost environment variables
+    if "BLOCKFROST_PROJECT_ID" in os.environ:
+        set_backend(
+            BlockFrostBackend(
+                project_id=os.environ["BLOCKFROST_PROJECT_ID"],
+            ),
+        )
+        return
+
+    # Check for Ogmios and Kupo environment variables
+    ogmios_kupo_vars = [
+        "OGMIOS_URL",
+        "KUPO_URL",
+        "CARDANO_NETWORK",
+    ]
+    if all(env_var in os.environ for env_var in ogmios_kupo_vars):
+        network = (
+            Network.MAINNET
+            if os.environ["CARDANO_NETWORK"].upper() == "MAINNET"
+            else Network.TESTNET
+        )
+        set_backend(
+            OgmiosKupoBackend(
+                ogmios_url=os.environ["OGMIOS_URL"],
+                kupo_url=os.environ["KUPO_URL"],
+                network=network,
+            ),
+        )
+        return
+
+    # If no backend can be set, log a warning
+    logging.warning("No default backend could be set. Please set a backend manually.")
+
+
+# Initialize the backend when the module is imported
 set_default_backend()

{charli3_dendrite-1.1.0.dev1 → charli3_dendrite-1.1.1.dev0}/src/charli3_dendrite/backend/backend_base.py

@@ -3,9 +3,11 @@
 from abc import ABC
 from abc import abstractmethod
 from datetime import datetime
+from typing import Optional
 
-from pycardano import Address
+from pycardano import Address  # type: ignore
 
+from charli3_dendrite.dataclasses.models import Assets
 from charli3_dendrite.dataclasses.models import BlockList
 from charli3_dendrite.dataclasses.models import PoolStateList
 from charli3_dendrite.dataclasses.models import ScriptReference
@@ -20,10 +22,10 @@ class AbstractBackend(ABC):
     """
 
     @abstractmethod
-    def get_pool_utxos(  # noqa: PLR0913
+    def get_pool_utxos(
         self,
+        addresses: list[str],
         assets: list[str] | None = None,
-        addresses: list[str] | None = None,
         limit: int = 1000,
         page: int = 0,
         historical: bool = True,
@@ -46,8 +48,8 @@ class AbstractBackend(ABC):
     def get_pool_in_tx(
         self,
         tx_hash: str,
+        addresses: list[str],
         assets: list[str] | None = None,
-        addresses: list[str] | None = None,
     ) -> PoolStateList:
         """Get pool state for a specific transaction.
 
@@ -119,7 +121,7 @@ class AbstractBackend(ABC):
         pass
 
     @abstractmethod
-    def get_order_utxos_by_block_or_tx(  # noqa: PLR0913
+    def get_order_utxos_by_block_or_tx(
         self,
         stake_addresses: list[str],
         out_tx_hash: list[str] | None = None,
@@ -146,7 +148,7 @@ class AbstractBackend(ABC):
         pass
 
     @abstractmethod
-    def get_cancel_utxos(  # noqa: PLR0913
+    def get_cancel_utxos(
         self,
         stake_addresses: list[str],
         block_no: int | None = None,
@@ -173,7 +175,7 @@ class AbstractBackend(ABC):
         self,
         address: str,
         asset: str | None = None,
-    ) -> str | None:
+    ) -> Optional[ScriptReference]:
         """Get datum from a given address.
 
         Args:
@@ -184,3 +186,20 @@ class AbstractBackend(ABC):
             The datum associated with the address, if any.
         """
         pass
+
+    @abstractmethod
+    def get_axo_target(
+        self,
+        assets: Assets,
+        block_time: datetime | None = None,
+    ) -> str | None:
+        """Get the target address for the given assets.
+
+        Args:
+            assets: The assets to query.
+            block_time: The block time to query.
+
+        Returns:
+            The target address for the assets, if any.
+        """
+        pass