Metadata-Version: 2.4
Name: plp-contract
Version: 2.0.1
Summary: Python client library for PLP (Protocol Liquidity Pool) smart contract interactions
Author-email: Daniel Mercer <mhoonumabaamercy@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/mhoonumabaamercy-hub/plp-contract
Project-URL: Documentation, https://github.com/mhoonumabaamercy-hub/plp-contract#readme
Project-URL: Repository, https://github.com/mhoonumabaamercy-hub/plp-contract
Project-URL: Issues, https://github.com/mhoonumabaamercy-hub/plp-contract/issues
Keywords: ethereum,defi,smart-contracts,web3,liquidity-pool,depositor
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-contracts>=2.0.0
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

# plp-contract

Python client library for PLP (Protocol Liquidity Pool) smart contract interactions. Provides typed, async-ready depositor and pool management clients built on `web3.py`.

## Installation

```bash
pip install plp-contract
```

## Quick Start

```python
from plp_contract import SimpleDepositor, DepositParams

depositor = SimpleDepositor(
    rpc_url="https://eth.llamarpc.com",
    depositor_address="0x8cad6c2317233D38a3cf4601F4A441f316F77Db3",
    private_key="0x...",
    chain_id=1,
)

# Preview deposit
shares = depositor.preview_deposit(
    pool_address="0x...",
    amount_wei=10**18,
)
print(f"Expected shares: {shares}")

# Execute deposit
result = depositor.deposit(DepositParams(
    pool_address="0x...",
    amount_wei=10**18,
    min_shares=int(shares * 0.995),  # 0.5% slippage
))
print(f"TX: {result.tx_hash}")
```

## Async Usage

```python
import asyncio
from plp_contract import AsyncDepositor, DepositParams

async def main():
    async with AsyncDepositor(
        rpc_url="wss://eth.llamarpc.com",
        depositor_address="0x8cad6c2317233D38a3cf4601F4A441f316F77Db3",
        private_key="0x...",
        chain_id=1,
    ) as depositor:
        info = await depositor.get_pool_info("0x...")
        print(f"TVL: {info.tvl_eth:.2f} ETH")

        result = await depositor.deposit(DepositParams(
            pool_address="0x...",
            amount_wei=5 * 10**17,
        ))
        print(f"TX: {result.tx_hash}, gas: {result.gas_used}")

asyncio.run(main())
```

## Pool Registry

Track and query multiple pools:

```python
from web3 import Web3
from plp_contract import PoolRegistry

w3 = Web3(Web3.HTTPProvider("https://eth.llamarpc.com"))
registry = PoolRegistry(w3, depositor_address="0x8cad6c...")

registry.add("0xPool1...")
registry.add("0xPool2...")

for pool in registry.active():
    print(f"{pool.name}: TVL={pool.tvl_eth:.2f} ETH, price={pool.share_price:.6f}")
```

## API Reference

### `SimpleDepositor` / `AsyncDepositor`

| Method | Description |
|--------|-------------|
| `deposit(params)` | Deposit assets into a pool (handles approval) |
| `withdraw(params)` | Withdraw by burning share tokens |
| `withdraw_all(pool, ...)` | Withdraw entire share balance |
| `get_pool_info(pool)` | Fetch on-chain pool state |
| `preview_deposit(pool, amount)` | Estimate shares for deposit |
| `preview_redeem(pool, shares)` | Estimate assets for redemption |
| `balance_of(pool, account?)` | Query share token balance |

### Models

- **`DepositParams`** — Validated deposit parameters with slippage protection
- **`WithdrawParams`** — Validated withdrawal parameters
- **`PoolInfo`** — Read-only pool state snapshot
- **`TransactionResult`** — On-chain transaction receipt with parsed logs
- **`GasConfig`** — EIP-1559 and legacy gas settings

### Exceptions

| Exception | When |
|-----------|------|
| `InsufficientBalanceError` | Balance below requested amount |
| `SlippageExceededError` | Output below minimum threshold |
| `PoolNotFoundError` | Pool address not registered |
| `TransactionRevertedError` | On-chain revert |
| `RPCError` | Provider communication failure |
| `GasEstimationError` | Gas estimation fails |

## Supported Contracts

| Contract | Address | Chain |
|----------|---------|-------|
| ELP Depositor | `0x8cad6c2317233D38a3cf4601F4A441f316F77Db3` | Ethereum |
| Royco Vault | `0x1F8B025D61Cd54E81B6e4f4fC1A8fc757bc50bcf` | Ethereum |

## Requirements

- Python 3.9+
- web3.py >= 6.0

## License

MIT
