Metadata-Version: 2.4
Name: gigadex-sdk
Version: 0.3.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 typed foundation for reading GigaDex data, working with concentrated-liquidity prices and ticks, loading verified contract ABIs, and preparing inspectable Web3 transaction plans.

It is useful for:

- liquidity tooling 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.

For detailed examples covering nearly every public module, see the full [SDK usage guide](docs/USAGE.md).

## Features

- **GigaDex GraphQL client** for tokens, pools, positions, and portfolio state.
- **Typed Pydantic models** for safer application code.
- **Pool discovery helpers** for filtering, finding, and sorting CL/classic pools.
- **DEX-wide stats and portfolio summaries** backed by GraphQL models where data is available.
- **Concentrated-liquidity math** for ticks, prices, ranges, and tick-spacing alignment.
- **Packaged ABI loading** for common GigaDex/Web3 contract interactions.
- **Canonical Robinhood Chain contract registry** for core, concentrated-liquidity,
  routing, and classic-liquidity contracts.
- **Low-level calldata builders** for ERC-20 approvals/transfers, swaps/quotes,
  CL positions, classic liquidity, CL/classic MasterChef earnings, and multicalls.
- **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 = "0x0000000000000000000000000000000000000000"

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)
```

### List, filter, and sort pools

```python
from gigadex_sdk.graphql_client import GigaDexGraphQLClient
from gigadex_sdk.pools import filter_pools, sort_pools

client = GigaDexGraphQLClient("https://edge.gigadex.fi/v1/graphql")
pools = client.fetch_pools(chain_id=4663, page_size=100)

cl_pools = filter_pools(pools, kind="cl")
top_by_tvl = sort_pools(cl_pools, by="tvl")[:10]

for pool in top_by_tvl:
    print(pool.address, pool.token0, pool.token1, pool.fee, pool.total_value_locked_usd)
```

### Fetch DEX-wide stats

```python
from gigadex_sdk.graphql_client import GigaDexGraphQLClient

client = GigaDexGraphQLClient("https://edge.gigadex.fi/v1/graphql")
stats = client.fetch_dex_stats(chain_id=4663)

print(stats.total_value_locked_usd, stats.volume24h_usd, stats.pool_count)
```

### Plan a swap without sending it

```python
from gigadex_sdk.contracts import ROBINHOOD_CONTRACTS
from gigadex_sdk.swaps import ExactInputSingleSwap, SwapPlanner, min_amount_out

planner = SwapPlanner()

# Usually this comes from a quoter call or simulation. The helper only applies
# explicit slippage math; it does not fetch prices by itself.
quoted_out = 1_000_000
amount_out_min = min_amount_out(quoted_out, slippage_bps=50)  # 0.50%

call = planner.exact_input_single_call(
    ExactInputSingleSwap(
        token_in=ROBINHOOD_CONTRACTS.weth,
        token_out=ROBINHOOD_CONTRACTS.usdg,
        fee=500,
        recipient="0x0000000000000000000000000000000000000000",
        amount_in=10**18,
        amount_out_minimum=amount_out_min,
    )
)

print(call.target)    # smart router address
print(call.calldata)  # review/simulate before signing elsewhere
```

### Plan ERC-20 approvals and liquidity calls

```python
from gigadex_sdk.contracts import ROBINHOOD_CONTRACTS
from gigadex_sdk.erc20 import ERC20Planner
from gigadex_sdk.position_manager import MintAmounts, MintPlan, PositionManagerPlanner

account = "0x0000000000000000000000000000000000000000"

erc20 = ERC20Planner()
approval = erc20.approve_call(
    token=ROBINHOOD_CONTRACTS.usdg,
    spender=ROBINHOOD_CONTRACTS.giga_positions,
    amount=1_000_000,
)

positions = PositionManagerPlanner()
mint = positions.mint_call(
    MintPlan(
        token0=ROBINHOOD_CONTRACTS.weth,
        token1=ROBINHOOD_CONTRACTS.usdg,
        fee=500,
        tick_lower=-200_200,
        tick_upper=-199_800,
        amounts=MintAmounts(10**18, 1_000_000, 99 * 10**16, 990_000),
        recipient=account,
        deadline=1_800_000_000,
    )
)

print(approval.calldata)
print(mint.calldata)
```

### Plan “claim all fees” for CL positions

```python
from gigadex_sdk.position_manager import PositionManagerPlanner

planner = PositionManagerPlanner()
calldata = planner.claim_all_fees_multicall_calldata(
    token_ids=[101, 102, 103],
    recipient="0x0000000000000000000000000000000000000000",
)

print(calldata)
```

### 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, GIGA_POSITIONS_ABI, abi_events

print(len(ERC20_ABI))
print(len(GIGA_POSITIONS_ABI))
print([event["name"] for event in abi_events(GIGA_POSITIONS_ABI)])
```

### Use known Robinhood Chain contracts

```python
from gigadex_sdk.contracts import ROBINHOOD_CHAIN_ID, contracts_for_chain

contracts = contracts_for_chain(ROBINHOOD_CHAIN_ID)

print(contracts.giga_positions)
print(contracts.cl_factory)
print(contracts.weth, contracts.usdg)
```

### Create a Web3 contract

```python
from dataclasses import dataclass

from gigadex_sdk.abis import ERC20_ABI
from gigadex_sdk.chain import ChainClient
from gigadex_sdk.contracts import ROBINHOOD_CHAIN_ID


@dataclass
class Settings:
    rpc_url: str
    chain_id: int = ROBINHOOD_CHAIN_ID
    private_key: str = ""
    account_address: str = ""
    max_gas_price_wei: int | None = None
    gas_limit_multiplier: float = 1.2
    wait_for_receipt_seconds: int = 0

    def require_rpc(self) -> None:
        if not self.rpc_url:
            raise ValueError("rpc_url is required")

    def require_wallet(self) -> None:
        if not self.private_key or not self.account_address:
            raise ValueError("wallet config is required")


chain_client = ChainClient(Settings(rpc_url="https://your-rpc.example"))
token = chain_client.contract("0x0000000000000000000000000000000000000000", ERC20_ABI)
```

## Common constants

```python
GIGADEX_GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
ROBINHOOD_CHAIN_ID = 4663
```

## Contract coverage

The SDK ships the known verified GigaDex contract addresses for Robinhood Chain:

- core/governance: controller, emission center, vault, fee center, fee receiver, WETH
- concentrated liquidity: CL factory/deployer/router/quoters, Giga Positions,
  CL MasterChef, LM pool deployer, position descriptor
- routing/classic liquidity: smart router, mixed quoter, tick lens, interface
  multicall, classic factory/router/MasterChef

Addresses are exposed as lowercase strings for stable comparisons and config.
Convert with `Web3.to_checksum_address(...)` before constructing Web3 contracts.

## SDK boundary

This package is intentionally a reusable SDK, not a keeper bot. It provides the
basic building blocks for GigaDex integrations: data fetching, typed models,
contract addresses, ABI loading, Web3 helpers, CL math, and low-level calldata
builders. Strategy code such as “rebalance when near edge”, alerting, retries,
position sizing, private-key policy, or fully automated execution should live in
separate applications that depend on this SDK.

The write-side modules deliberately return calldata or transaction-plan objects.
They do not sign or send transactions by default. Review, simulate, and apply
your own gas/slippage/private-key policy in the application layer.

## 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.

Pool creation transaction execution is intentionally not implemented yet. The
SDK exposes only safe calldata-building extension points where the packaged ABIs
support them; full pool-creation workflows should be added later with tests,
simulation guidance, and clear review steps.

## Contributing

Contributions are welcome. For development setup, test commands, release steps, and PyPI publishing notes, see [`README-DEV.md`](README-DEV.md).

## License

MIT

