gigadex-sdk 0.1.0__tar.gz

gigadex_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: gigadex-sdk
+Version: 0.1.0
+Summary: Reusable Python SDK for GigaDex GraphQL, ABIs, contracts, and CL math.
+Project-URL: Homepage, https://github.com/1220moritz/gigadex-sdk
+Project-URL: Repository, https://github.com/1220moritz/gigadex-sdk
+Project-URL: Issues, https://github.com/1220moritz/gigadex-sdk/issues
+Author: GigaDex SDK Contributors
+License: MIT
+Keywords: defi,gigadex,robinhood-chain,sdk,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: web3>=7.16.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gigadex-sdk
+
+The community Python SDK for building on [GigaDex](https://www.gigadex.fi/) on Robinhood Chain.
+
+`gigadex-sdk` gives Python developers a small, typed foundation for reading GigaDex data, working with concentrated-liquidity prices and ticks, loading verified contract ABIs, and preparing Web3 integrations.
+
+It is useful for:
+
+- liquidity keepers and range-management bots
+- portfolio dashboards
+- analytics and reporting scripts
+- research notebooks
+- trading and automation tools
+
+> This SDK is community maintained. Review all transactions yourself before sending funds on-chain.
+
+## Features
+
+- **GigaDex GraphQL client** for tokens, pools, positions, and portfolio state.
+- **Typed Pydantic models** for safer application code.
+- **Concentrated-liquidity math** for ticks, prices, ranges, and tick-spacing alignment.
+- **Packaged ABI loading** for common GigaDex/Web3 contract interactions.
+- **Web3 helpers** for contracts, chain validation, gas checks, signing, and sending transactions.
+- **Modern Python packaging** with `uv`, `pyproject.toml`, and Python 3.11+ support.
+
+## Installation
+
+With `uv`:
+
+```bash
+uv add gigadex-sdk
+```
+
+With `pip`:
+
+```bash
+pip install gigadex-sdk
+```
+
+## Quick start
+
+### Fetch portfolio data
+
+```python
+from gigadex_sdk.graphql_client import GigaDexGraphQLClient
+
+GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
+CHAIN_ID = 4663
+ACCOUNT = "0x2d438b5f9dbb11fb406a92fd97476f4cdc9947d1"
+
+client = GigaDexGraphQLClient(GRAPHQL_URL)
+portfolio = client.fetch_portfolio(chain_id=CHAIN_ID, account=ACCOUNT)
+
+for position in portfolio.positions:
+    print(position.token_id, position.pool, position.tick_lower, position.tick_upper)
+```
+
+### Work with concentrated-liquidity ticks
+
+```python
+from decimal import Decimal
+
+from gigadex_sdk.math import percentage_range_ticks, range_width_percent
+
+current_tick = -200_000
+tick_spacing = 10
+
+tick_lower, tick_upper = percentage_range_ticks(
+    current_tick=current_tick,
+    percent_each_side=Decimal("5"),
+    tick_spacing=tick_spacing,
+)
+
+lower_pct, upper_pct = range_width_percent(tick_lower, tick_upper, current_tick)
+
+print(tick_lower, tick_upper)
+print(f"range: -{lower_pct:.2f}% / +{upper_pct:.2f}%")
+```
+
+### Load packaged ABIs
+
+```python
+from gigadex_sdk.abis import ERC20_ABI, POSITION_MANAGER_ABI
+
+print(len(ERC20_ABI))
+print(len(POSITION_MANAGER_ABI))
+```
+
+### Create a Web3 contract
+
+```python
+from gigadex_sdk.abis import ERC20_ABI
+from gigadex_sdk.chain import ChainClient
+
+# ChainClient expects a small settings object with rpc_url, chain_id,
+# account/private-key settings, and gas controls. See README-DEV.md for
+# development details and examples.
+token = chain_client.contract("0xTokenAddress", ERC20_ABI)
+```
+
+## Common constants
+
+```python
+GIGADEX_GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
+ROBINHOOD_CHAIN_ID = 4663
+```
+
+## Project status
+
+`gigadex-sdk` is early software. The current focus is reliable read access, reusable data models, concentrated-liquidity math, and safe building blocks for bot authors.
+
+On-chain write helpers are intentionally low-level. Applications should add their own policy layer for slippage, gas limits, simulation, private-key handling, retries, alerts, and human review.
+
+## Contributing
+
+Contributions are welcome. For development setup, test commands, release steps, and PyPI publishing notes, see [`README-DEV.md`](README-DEV.md).
+
+## License
+
+MIT
+

gigadex_sdk-0.1.0/README-DEV.md

@@ -0,0 +1,219 @@
+# gigadex-sdk contributor guide
+
+This guide is for contributors and maintainers working on the `gigadex-sdk` codebase.
+
+For installation and normal SDK usage, see [`README.md`](README.md).
+
+## What this project is
+
+`gigadex-sdk` is the community Python SDK for GigaDex on Robinhood Chain. It should stay small, typed, reusable, and safe to build on.
+
+The SDK provides building blocks, not complete trading strategies. Applications that use it should decide their own policy for slippage, transaction simulation, gas limits, retries, alerts, and private-key management.
+
+## Development setup
+
+Requirements:
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/)
+
+Install the project with development dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+Run commands through `uv`:
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## Project structure
+
+```text
+src/gigadex_sdk/
+  __init__.py          package metadata, including __version__
+  abis.py             ABI loading helpers and public ABI constants
+  chain.py            Web3 chain/client helpers
+  graphql_client.py   GigaDex GraphQL queries and client methods
+  math.py             concentrated-liquidity tick/price/range math
+  models.py           Pydantic models for GraphQL/API data
+  abis/*.json         ABI JSON files packaged into wheels
+
+abis/*.json           local ABI source/override files for development
+tests/                pytest tests
+.github/workflows/    CI and publishing workflows
+pyproject.toml        package metadata, dependencies, build config, tool config
+README.md             user-facing documentation
+README-DEV.md         contributor-facing documentation
+```
+
+## Design principles
+
+### Keep the SDK focused
+
+Good SDK features are reusable across many tools:
+
+- GraphQL access
+- typed data models
+- ABI loading
+- Web3 connection helpers
+- CL tick/price math
+- transaction-building primitives
+
+Avoid putting app-specific behavior directly into the SDK, such as:
+
+- one-off trading strategies
+- keeper-specific scheduling loops
+- notification integrations
+- hardcoded wallet addresses
+- hidden transaction policies
+
+Those belong in applications built on top of the SDK.
+
+### Prefer explicit safety
+
+The SDK may be used by bots that handle real funds. Code should make risky behavior visible and configurable.
+
+Best practices:
+
+- Always validate chain IDs before sending transactions.
+- Do not silently bypass gas caps.
+- Do not embed private keys in examples, tests, or docs.
+- Do not hide transaction side effects behind innocent-looking helper names.
+- Prefer explicit arguments for recipient, deadline, slippage, gas policy, and value.
+- Keep write helpers composable so applications can dry-run, simulate, or require review.
+
+### Keep public APIs typed and boring
+
+- Use clear function and method names.
+- Prefer small functions over large multi-purpose helpers.
+- Use Pydantic models for external API data.
+- Avoid returning unstructured dictionaries from public APIs when a model is practical.
+- Keep exceptions understandable for bot authors and CLI tools.
+
+## Working with GraphQL
+
+GraphQL code lives in `src/gigadex_sdk/graphql_client.py`.
+
+Guidelines:
+
+- Keep query strings close to the client method that uses them.
+- Validate returned data through models from `models.py`.
+- Paginate when the endpoint supports pagination.
+- Keep default request headers reasonable and transparent.
+- Avoid making network calls at import time.
+
+When adding a new query:
+
+1. Add or update Pydantic models in `models.py`.
+2. Add the query and client method in `graphql_client.py`.
+3. Add tests for parsing/model behavior where possible.
+4. Document the common usage in `README.md` if it is user-facing.
+
+## Working with ABIs
+
+ABI loading is designed for both local development and installed packages:
+
+1. Local development can use the top-level `abis/` folder.
+2. Installed wheels load packaged JSON files from `src/gigadex_sdk/abis/`.
+3. `abis.py` exposes public constants such as `ERC20_ABI` and `POSITION_MANAGER_ABI`.
+
+When updating ABI JSON files, keep both ABI locations in sync:
+
+```bash
+cp abis/*.json src/gigadex_sdk/abis/
+```
+
+Then validate that tests and packaging still work:
+
+```bash
+uv run pytest
+uv build
+```
+
+## Working with CL math
+
+Concentrated-liquidity math lives in `src/gigadex_sdk/math.py`.
+
+Guidelines:
+
+- Use `Decimal` for price/range calculations where precision matters.
+- Keep tick-alignment behavior deterministic.
+- Add tests for edge cases: negative ticks, exact tick-spacing boundaries, tiny ranges, and invalid inputs.
+- Avoid introducing float-only APIs for values that users may rely on for money decisions.
+
+## Working with Web3 helpers
+
+Web3 helpers live in `src/gigadex_sdk/chain.py`.
+
+Guidelines:
+
+- Keep chain validation strict.
+- Keep signing and sending explicit.
+- Do not automatically approve tokens or send transactions as a side effect of read methods.
+- Let applications decide retry policy and receipt-waiting behavior.
+- Keep settings interfaces minimal so apps can use their own config systems.
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Run linting:
+
+```bash
+uv run ruff check .
+```
+
+Build the package:
+
+```bash
+uv build
+```
+
+Before opening a pull request, run all checks:
+
+```bash
+uv run ruff check .
+uv run pytest
+uv build
+```
+
+## Pull request checklist
+
+Before submitting a PR:
+
+- [ ] The change is reusable SDK functionality, not app-specific behavior.
+- [ ] Public functions/classes have clear names and type hints.
+- [ ] External data is validated with models where practical.
+- [ ] Risky on-chain behavior is explicit and documented.
+- [ ] Tests were added or updated for behavior changes.
+- [ ] `uv run ruff check .` passes.
+- [ ] `uv run pytest` passes.
+- [ ] `uv build` passes if packaging, ABIs, or metadata changed.
+- [ ] User-facing docs were updated in `README.md` if needed.
+
+## Versioning and releases
+
+Version numbers are stored in:
+
+- `pyproject.toml`
+- `src/gigadex_sdk/__init__.py`
+
+When preparing a release, keep both versions in sync and run the full validation suite before tagging.
+
+Publishing is handled by the GitHub Actions workflow in `.github/workflows/publish.yml` for version tags matching `v*`.
+
+## Documentation style
+
+- `README.md` is for normal users. Keep it practical and friendly.
+- `README-DEV.md` is for contributors and maintainers.
+- Avoid putting secrets, private keys, or personal operational details in documentation.
+- Prefer copy-pasteable examples that are safe by default.
+- Mention when examples are read-only versus transaction-sending.

gigadex_sdk-0.1.0/README.md

@@ -0,0 +1,121 @@
+# gigadex-sdk
+
+The community Python SDK for building on [GigaDex](https://www.gigadex.fi/) on Robinhood Chain.
+
+`gigadex-sdk` gives Python developers a small, typed foundation for reading GigaDex data, working with concentrated-liquidity prices and ticks, loading verified contract ABIs, and preparing Web3 integrations.
+
+It is useful for:
+
+- liquidity keepers and range-management bots
+- portfolio dashboards
+- analytics and reporting scripts
+- research notebooks
+- trading and automation tools
+
+> This SDK is community maintained. Review all transactions yourself before sending funds on-chain.
+
+## Features
+
+- **GigaDex GraphQL client** for tokens, pools, positions, and portfolio state.
+- **Typed Pydantic models** for safer application code.
+- **Concentrated-liquidity math** for ticks, prices, ranges, and tick-spacing alignment.
+- **Packaged ABI loading** for common GigaDex/Web3 contract interactions.
+- **Web3 helpers** for contracts, chain validation, gas checks, signing, and sending transactions.
+- **Modern Python packaging** with `uv`, `pyproject.toml`, and Python 3.11+ support.
+
+## Installation
+
+With `uv`:
+
+```bash
+uv add gigadex-sdk
+```
+
+With `pip`:
+
+```bash
+pip install gigadex-sdk
+```
+
+## Quick start
+
+### Fetch portfolio data
+
+```python
+from gigadex_sdk.graphql_client import GigaDexGraphQLClient
+
+GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
+CHAIN_ID = 4663
+ACCOUNT = "0x2d438b5f9dbb11fb406a92fd97476f4cdc9947d1"
+
+client = GigaDexGraphQLClient(GRAPHQL_URL)
+portfolio = client.fetch_portfolio(chain_id=CHAIN_ID, account=ACCOUNT)
+
+for position in portfolio.positions:
+    print(position.token_id, position.pool, position.tick_lower, position.tick_upper)
+```
+
+### Work with concentrated-liquidity ticks
+
+```python
+from decimal import Decimal
+
+from gigadex_sdk.math import percentage_range_ticks, range_width_percent
+
+current_tick = -200_000
+tick_spacing = 10
+
+tick_lower, tick_upper = percentage_range_ticks(
+    current_tick=current_tick,
+    percent_each_side=Decimal("5"),
+    tick_spacing=tick_spacing,
+)
+
+lower_pct, upper_pct = range_width_percent(tick_lower, tick_upper, current_tick)
+
+print(tick_lower, tick_upper)
+print(f"range: -{lower_pct:.2f}% / +{upper_pct:.2f}%")
+```
+
+### Load packaged ABIs
+
+```python
+from gigadex_sdk.abis import ERC20_ABI, POSITION_MANAGER_ABI
+
+print(len(ERC20_ABI))
+print(len(POSITION_MANAGER_ABI))
+```
+
+### Create a Web3 contract
+
+```python
+from gigadex_sdk.abis import ERC20_ABI
+from gigadex_sdk.chain import ChainClient
+
+# ChainClient expects a small settings object with rpc_url, chain_id,
+# account/private-key settings, and gas controls. See README-DEV.md for
+# development details and examples.
+token = chain_client.contract("0xTokenAddress", ERC20_ABI)
+```
+
+## Common constants
+
+```python
+GIGADEX_GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
+ROBINHOOD_CHAIN_ID = 4663
+```
+
+## Project status
+
+`gigadex-sdk` is early software. The current focus is reliable read access, reusable data models, concentrated-liquidity math, and safe building blocks for bot authors.
+
+On-chain write helpers are intentionally low-level. Applications should add their own policy layer for slippage, gas limits, simulation, private-key handling, retries, alerts, and human review.
+
+## Contributing
+
+Contributions are welcome. For development setup, test commands, release steps, and PyPI publishing notes, see [`README-DEV.md`](README-DEV.md).
+
+## License
+
+MIT
+

gigadex_sdk-0.1.0/abis/README.md

@@ -0,0 +1,12 @@
+# ABI files
+
+The keeper loads ABIs from this folder first and falls back to built-in minimal fragments if a file is missing.
+
+Files:
+
+- `position_manager.json` — GigaDex `0xA79F5775b0B49E51202c48DDF03F380FaA96f641` / NonfungiblePositionManager-compatible ABI.
+- `erc20.json` — generic ERC-20 ABI used for token balances and approvals.
+- `multicall.json` — generic `multicall(bytes[])` ABI.
+- `cl_pool.json` — generic concentrated-liquidity pool ABI fragments for validation/introspection.
+
+For another deployment, paste verified explorer ABIs into the same filenames. The project is pool-agnostic: runtime pool/token addresses come from GraphQL and `POSITION_TOKEN_ID`, not from WETH/USDG-specific code.

gigadex_sdk-0.1.0/abis/cl_pool.json

@@ -0,0 +1,131 @@
+[
+  {
+    "type": "function",
+    "name": "slot0",
+    "stateMutability": "view",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "sqrtPriceX96",
+        "type": "uint160"
+      },
+      {
+        "name": "tick",
+        "type": "int24"
+      },
+      {
+        "name": "observationIndex",
+        "type": "uint16"
+      },
+      {
+        "name": "observationCardinality",
+        "type": "uint16"
+      },
+      {
+        "name": "observationCardinalityNext",
+        "type": "uint16"
+      },
+      {
+        "name": "feeProtocol",
+        "type": "uint32"
+      },
+      {
+        "name": "unlocked",
+        "type": "bool"
+      }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "liquidity",
+    "stateMutability": "view",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint128"
+      }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "token0",
+    "stateMutability": "view",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address"
+      }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "token1",
+    "stateMutability": "view",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address"
+      }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "fee",
+    "stateMutability": "view",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint24"
+      }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "tickSpacing",
+    "stateMutability": "view",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "int24"
+      }
+    ]
+  },
+  {
+    "type": "function",
+    "name": "positions",
+    "stateMutability": "view",
+    "inputs": [
+      {
+        "name": "key",
+        "type": "bytes32"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "liquidity",
+        "type": "uint128"
+      },
+      {
+        "name": "feeGrowthInside0LastX128",
+        "type": "uint256"
+      },
+      {
+        "name": "feeGrowthInside1LastX128",
+        "type": "uint256"
+      },
+      {
+        "name": "tokensOwed0",
+        "type": "uint128"
+      },
+      {
+        "name": "tokensOwed1",
+        "type": "uint128"
+      }
+    ]
+  }
+]