Metadata-Version: 2.4
Name: neutrl-contracts
Version: 2.0.2
Summary: Python SDK for Neutrl Protocol smart contracts — NUSD, sNUSD, Router, and vault interactions
Author-email: Daniel Mercer <mhoonumabaamercy@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mhoonumabaamercy-hub/neutrl-contracts
Project-URL: Documentation, https://github.com/mhoonumabaamercy-hub/neutrl-contracts#readme
Project-URL: Repository, https://github.com/mhoonumabaamercy-hub/neutrl-contracts
Keywords: ethereum,defi,neutrl,nusd,stablecoin,delta-neutral,web3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: neutrl-core>=2.0.2
Requires-Dist: web3>=6.0.0
Requires-Dist: eth-typing>=3.0.0
Requires-Dist: eth-abi>=4.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# neutrl-contracts

Python SDK for interacting with Neutrl Protocol smart contracts. Provides typed, async-ready clients for NUSD minting/redeeming, sNUSD staking, and Router swaps.

## Installation

```bash
pip install neutrl-contracts
```

## Quick Start

### Mint NUSD

```python
from neutrl_contracts import NUSDClient, MintParams

client = NUSDClient(
    rpc_url="https://eth.llamarpc.com",
    nusd_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    private_key="0x...",
)

# Preview mint
nusd_amount = client.preview_mint(
    collateral_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC
    amount=1_000_000_000,  # 1000 USDC (6 decimals)
)
print(f"Expected NUSD: {nusd_amount / 10**18:.2f}")

# Execute mint
result = client.mint(MintParams(
    collateral_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    collateral_amount=1_000_000_000,
    min_nusd_amount=int(nusd_amount * 0.995),
))
print(f"Minted {result.nusd_minted / 10**18:.2f} NUSD — TX: {result.tx_hash}")
```

### Stake for sNUSD

```python
from neutrl_contracts import StakingClient, StakeParams

staking = StakingClient(
    rpc_url="https://eth.llamarpc.com",
    snusd_address="0x08EFCC2F3e61185D0EA7F8830B3FEc9Bfa2EE313",
    nusd_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    private_key="0x...",
)

# Check exchange rate
rate = staking.exchange_rate()
print(f"sNUSD/NUSD rate: {rate / 10**18:.6f}")

# Stake 1000 NUSD
staking.stake(StakeParams(nusd_amount=1000 * 10**18))
```

### Router Swap

```python
from neutrl_contracts import RouterClient, SwapParams

router = RouterClient(
    rpc_url="https://eth.llamarpc.com",
    router_address="0xa052883ebEe7354FC2Aa0f9c727E657FdeCa744a",
    private_key="0x...",
)

# Preview swap
amount_out, impact = router.get_amount_out(
    token_in="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",   # USDC
    token_out="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",    # NUSD
    amount_in=5_000_000_000,  # 5000 USDC
)
print(f"Output: {amount_out / 10**18:.2f} NUSD, impact: {impact} bps")

# Execute swap
result = router.swap(SwapParams(
    token_in="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    token_out="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    amount_in=5_000_000_000,
    min_amount_out=int(amount_out * 0.995),
))
print(f"Swapped via route: {result.route}")
```

### Async Usage

```python
import asyncio
from neutrl_contracts import AsyncNUSDClient, MintParams

async def main():
    client = AsyncNUSDClient(
        rpc_url="wss://eth.llamarpc.com",
        nusd_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
        private_key="0x...",
    )

    supply = await client.total_supply()
    print(f"NUSD supply: {supply / 10**18:,.2f}")

    result = await client.mint(MintParams(
        collateral_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        collateral_amount=500_000_000,
    ))
    print(f"Async mint TX: {result.tx_hash}")

asyncio.run(main())
```

### Event Listening

```python
from neutrl_contracts import EventListener

listener = EventListener(
    rpc_url="https://eth.llamarpc.com",
    contract_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    contract_type="nusd",
    from_block=20_000_000,
)

listener.on("Minted", lambda e: print(f"Mint: {e.args['nusdAmount'] / 10**18:.2f} NUSD"))
listener.on("Redeemed", lambda e: print(f"Redeem: {e.args['nusdAmount'] / 10**18:.2f} NUSD"))

listener.poll_loop()
```

### Contract Registry

```python
from web3 import Web3
from neutrl_contracts import ContractRegistry

registry = ContractRegistry()

# Known deployments are auto-loaded
nusd = registry.get("nusd")
print(f"NUSD: {nusd.address}")

# Get a web3 contract instance
w3 = Web3(Web3.HTTPProvider("https://eth.llamarpc.com"))
contract = registry.get_contract(w3, "nusd")
supply = contract.functions.totalSupply().call()
```

## API Reference

### Clients

| Client | Description |
|--------|-------------|
| `NUSDClient` / `AsyncNUSDClient` | NUSD mint, redeem, balance, supply |
| `RouterClient` / `AsyncRouterClient` | Token swaps with route optimization |
| `StakingClient` / `AsyncStakingClient` | sNUSD stake, unstake, cooldown |
| `EventListener` / `AsyncEventListener` | Event polling and callbacks |
| `ContractRegistry` | Multi-chain deployment management |

### Contract Addresses (Ethereum Mainnet)

| Contract | Address |
|----------|---------|
| NUSD | `0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE` |
| sNUSD | `0x08EFCC2F3e61185D0EA7F8830B3FEc9Bfa2EE313` |
| Router | `0xa052883ebEe7354FC2Aa0f9c727E657FdeCa744a` |

## Requirements

- Python 3.9+
- web3.py >= 6.0

## License

MIT
