| Name | charli3_dendrite JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2024-09-13 00:46:14 |
| maintainer | None |
| docs_url | None |
| author | Elder Millenial |
| requires_python | <4.0,>=3.10 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<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.
Raw data
{
"_id": null,
"home_page": null,
"name": "charli3_dendrite",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Elder Millenial",
"author_email": "eldermillenial@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/8b/fc/ac52d8b8bf0810b98bca0f56a2e666ce75f2b51e4d3e2a2aede4dbb5f483/charli3_dendrite-1.1.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1 align=\"center\">Charli3 Dendrite</h1>\n <p align=\"center\">Python SDK for interacting with Cardano DEXs</p>\n <p>\n <img src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python version\">\n <img src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"License\">\n <img src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\" alt=\"PRs welcome\">\n </p>\n</div>\n\n## Overview\n\nCharli3 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.\n\n## Key Features\n\n- \ud83d\udd04 Multi-DEX Support: Integrate with Minswap, MuesliSwap, Spectrum, SundaeSwap, VyFi, GeniusYield, Axo, and WingRiders\n- \ud83d\udca7 Liquidity Pool Data: Fetch and analyze pool information across different DEXs\n- \ud83d\udcb1 Swap Operations: Execute token swaps with ease\n- \ud83e\udde9 Flexible Asset Handling: Manage various asset types and pool states efficiently\n- \ud83d\udd17 On-chain Data Integration: Connect with DB-sync, BlockFrost, and Ogmios/Kupo\n- \ud83d\udee0 Extensible Architecture: Easily add support for new DEXs and features\n\n\n## Installation\n\n```bash\n# Using pip\npip install charli3_dendrite\n\n# Using Poetry\npoetry add charli3_dendrite\n```\n\n## Supported DEXs\nCharli3 Dendrite currently supports the following Cardano DEXs:\n\n- Minswap\n- MuesliSwap\n- Spectrum\n- SundaeSwap\n- VyFi\n- WingRiders\n- GeniusYield\n- Axo\n\n### Not Yet Implemented\n\n- CardanoSwaps\n- Metadex\n- CSwap\n- TeddySwap\n- Cerra\n- SaturnSwap\n- Splash\n\nEach DEX is implemented as a separate module within the `charli3_dendrite.dexs.amm` package.\n\n## Configuration\nCharli3 Dendrite can be configured using environment variables or a `.env` file. See `sample.env` for an example of the configuration options.\n\n### Backend Configuration\n\nCharli3 Dendrite supports multiple backend options for interacting with the Cardano blockchain:\n\n#### DBSync Configuration\n\nTo use a DBSync instance as the blockchain connection, set the following environment variables:\n\n```bash\nDBSYNC_HOST=\"your-dbsync-host\"\nDBSYNC_PORT=\"your-dbsync-port\"\nDBSYNC_DB_NAME=\"your-dbsync-database-name\"\nDBSYNC_USER=\"your-dbsync-username\"\nDBSYNC_PASS=\"your-dbsync-password\"\n```\n\n#### BlockFrost Configuration\n\nTo use BlockFrost as the backend, set the following environment variables:\n\n```bash\nBLOCKFROST_PROJECT_ID=\"your-blockfrost-project-id\"\nCARDANO_NETWORK=\"mainnet\" # or \"testnet\" for the Cardano testnet\n```\n\n#### Ogmios/Kupo Configuration\n\nTo use Ogmios and Kupo as the backend, set the following environment variables:\n\n```bash\nOGMIOS_URL=\"ws://your-ogmios-url:port\"\nKUPO_URL=\"http://your-kupo-url:port\"\nCARDANO_NETWORK=\"mainnet\" # or \"testnet\" for the Cardano testnet\n```\n\nThe 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.\n\n### Backend Limitations\n\nWhile 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:\n\n- **BlockFrost Backend**: Due to limitations in the BlockFrost API, the following methods are not implemented:\n - `get_historical_order_utxos`\n - `get_order_utxos_by_block_or_tx`\n - `get_cancel_utxos`\n - `get_axo_target`\n\n- **Ogmios/Kupo Backend**: The Ogmios/Kupo backend also has limitations due to the nature of these services:\n - `get_historical_order_utxos`\n - `get_order_utxos_by_block_or_tx`\n - `get_cancel_utxos`\n\nThese 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.\n\n## Usage\n\n### Retrieving Orders and Pool Data\n\nTo retrieve orders and pool data, first configure the global backend:\n\n```python\nfrom charli3_dendrite.backend import set_backend, get_backend\nfrom charli3_dendrite.backend.dbsync import DbsyncBackend\nfrom charli3_dendrite.backend.blockfrost import BlockFrostBackend\nfrom charli3_dendrite.backend.ogmios_kupo import OgmiosKupoBackend\nfrom pycardano import Network\n\n# Choose one of the following backends:\n# set_backend(DbsyncBackend())\n# set_backend(BlockFrostBackend(\"your-project-id\"))\nset_backend(OgmiosKupoBackend(\"ws://ogmios-url:port\", \"http://kupo-url:port\", Network.MAINNET))\n\nbackend = get_backend()\n```\n\nThe `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.\n\nTo retrieve pool information, use the `pool_selector` method provided by each DEX's state class:\n\n```python\nfrom charli3_dendrite import VyFiCPPState\n\nselector = VyFiCPPState.pool_selector()\nresult = backend.get_pool_utxos(\n limit=100000,\n historical=False,\n **selector.model_dump(),\n)\n```\nTo process and parse the retrieved results (`list[PoolStateInfo]`), the following approach can be utilized:\n```python\npool_data = {}\ntotal_tvl = 0\nfor pool in result:\n d = dex.model_validate(pool.model_dump())\n try:\n logger.info(\"Get TVL %s\", d.tvl)\n logger.info(\"Price %s\", d.price)\n logger.info(\"Token name of asset A: %s\", d.unit_a)\n logger.info(\"Token name of asset B: %s\", d.unit_b)\n except NoAssetsError:\n pass\n except InvalidLPError:\n pass\n except InvalidPoolError:\n pass\n except Exception as e:\n logger.debug(f\"{dex.__name__}: {e}\")\n```\nThis approach is applicable across all supported DEXs. For example, the following list of AbstractPoolState subclasses can be defined to support various DEX states:\n```python\nDEXS: list[AbstractPoolState] = [\n GeniusYieldOrderState,\n MinswapCPPState,\n MinswapV2CPPState,\n MinswapDJEDiUSDStableState,\n MinswapDJEDUSDCStableState,\n MinswapDJEDUSDMStableState,\n MuesliSwapCPPState,\n SpectrumCPPState,\n SundaeSwapCPPState,\n SundaeSwapV3CPPState,\n VyFiCPPState,\n WingRidersCPPState,\n WingRidersSSPState,\n]\n```\n## Development\nTo set up the development environment:\n\n1. Clone the repository\n2. Install dependencies: `poetry install`\n3. Set up pre-commit hooks: `pre-commit install`\n\n## Running Tests\n```bash\npoetry run pytest --benchmark-disable -v --slow -n auto\n```\n\n## Contributing\nContributions to Charli3 Dendrite are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines on how to contribute to the project.\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "1.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1f1d573aeb7aef24abd69cb2690a1c027d57fe946afff25d3d2cc7ba2e4d2529",
"md5": "41146113bfd3e0dc10ee53aec6cc31ff",
"sha256": "9d264069a3c1b7fbc2ae92b81f54f00cc51dcc10f3156821f28a1a6f41ebf01f"
},
"downloads": -1,
"filename": "charli3_dendrite-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "41146113bfd3e0dc10ee53aec6cc31ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 76387,
"upload_time": "2024-09-13T00:46:12",
"upload_time_iso_8601": "2024-09-13T00:46:12.222830Z",
"url": "https://files.pythonhosted.org/packages/1f/1d/573aeb7aef24abd69cb2690a1c027d57fe946afff25d3d2cc7ba2e4d2529/charli3_dendrite-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8bfcac52d8b8bf0810b98bca0f56a2e666ce75f2b51e4d3e2a2aede4dbb5f483",
"md5": "d367624634210d57d2daf597caca0626",
"sha256": "086d85c1e1a2bc9519c2c8b943ab83883f75938b66b1baf4488d6b4c4d96ff84"
},
"downloads": -1,
"filename": "charli3_dendrite-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d367624634210d57d2daf597caca0626",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 60199,
"upload_time": "2024-09-13T00:46:14",
"upload_time_iso_8601": "2024-09-13T00:46:14.545728Z",
"url": "https://files.pythonhosted.org/packages/8b/fc/ac52d8b8bf0810b98bca0f56a2e666ce75f2b51e4d3e2a2aede4dbb5f483/charli3_dendrite-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-13 00:46:14",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "charli3_dendrite"
}
