Metadata-Version: 2.4
Name: conway-sdk
Version: 1.0.0
Summary: Python SDK for EIP-3009 payment signing and agent identity models
Project-URL: Homepage, https://github.com/dxpe_7/conway-sdk
Project-URL: Repository, https://github.com/dxpe_7/conway-sdk
Project-URL: Changelog, https://github.com/dxpe_7/conway-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/dxpe_7/conway-sdk/issues
Author: dxpe_7
License: MIT License
        
        
        =======
        Copyright (c) 2026 dxpe147
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: conway,eip3009,eip712,ethereum,payments,usdc,web3,x402
Classifier: Development Status :: 5 - Production/Stable
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: eth-account<1.0,>=0.11
Requires-Dist: eth-typing>=3.0
Requires-Dist: eth-utils>=2.0
Requires-Dist: pydantic<3.0,>=2.6
Provides-Extra: dev
Requires-Dist: anyio[trio]>=4.0; extra == 'dev'
Requires-Dist: fakeredis>=2.20; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: kms
Requires-Dist: boto3<2.0,>=1.34; extra == 'kms'
Requires-Dist: cryptography>=42.0; extra == 'kms'
Provides-Extra: redis
Requires-Dist: redis<7.0,>=5.0; extra == 'redis'
Description-Content-Type: text/markdown


# Conway SDK

![Status](https://img.shields.io/badge/status-stable-green)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-blue)

Conway SDK is a Python library for building payment-enabled agents using the
[x402](https://x402.org) protocol with EIP-3009 delegated USDC transfers.
It provides typed models, EVM wallet integrations, EIP-712 signing primitives,
and distributed nonce deduplication — without bundling runtime or persistence
logic.

---

## Installation

```bash
pip install conway-sdk
```

### Optional extras

```bash
# Redis nonce deduplication (multi-instance deployments)
pip install "conway-sdk[redis]"

# AWS KMS wallet (production signing)
pip install "conway-sdk[kms]"

# Development tools (pytest, ruff, mypy)
pip install "conway-sdk[dev]"
```

---

## Python version

Requires **Python 3.10 or later**.

---

## Core features

| Feature | Module |
|---------|--------|
| Typed agent and payment intent models | `conway_sdk.models` |
| EIP-3009 / EIP-712 signing | `conway_sdk.payment.eip3009` |
| Abstract wallet interface + local wallet | `conway_sdk.wallet` |
| AWS KMS wallet (optional) | `conway_sdk.wallet.kms` |
| Distributed Redis nonce cache (optional) | `conway_sdk.wallet.redis_nonce_cache` |
| CAIP-2 chain identifier utilities | `conway_sdk.payment.caip2` |
| Payment requirements / authorization models | `conway_sdk.payment.models` |
| Execution adapter interface | `conway_sdk.execution_adapter` |
| Structured exception hierarchy | `conway_sdk.exceptions` |

---

## Usage

### Signing a payment

```python
from conway_sdk import LocalWallet, EIP3009Signer
from conway_sdk.config import SdkConfig
from conway_sdk.payment.models import PaymentRequirements

# Load wallet from private key (use a secrets manager in production)
wallet = LocalWallet("0x<private_key_hex>")

# Configure the signer
config = SdkConfig(payment_timeout_seconds=300)
signer = EIP3009Signer(config)

# Build payment requirements (typically parsed from an HTTP 402 response)
requirements = PaymentRequirements(
    amount=1_000_000,          # 1 USDC (6 decimal places)
    chain_id=8453,             # Base Mainnet
    verifying_contract="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    pay_to="0x<recipient_address>",
)

# Sign synchronously
authorization = signer.sign(wallet, requirements)

# Attach the resulting headers to your retried HTTP request
headers = authorization.to_payment_headers()
```

### Parsing a 402 response header

```python
from conway_sdk.payment.models import PaymentRequirements

header = response.headers["PAYMENT-REQUIRED"]
requirements = PaymentRequirements.from_payment_required_header(header)
```

### Async signing

```python
authorization = await signer.sign_async(wallet, requirements)
```

### Redis nonce deduplication (multi-instance)

```python
import redis
from conway_sdk.wallet.redis_nonce_cache import RedisNonceCache

client = redis.Redis.from_url("redis://localhost:6379/0")
cache = RedisNonceCache(client)

is_fresh = cache.record(authorization.nonce)
if not is_fresh:
    raise RuntimeError("Duplicate nonce detected — refusing to submit.")
```

### CAIP-2 utilities

```python
from conway_sdk.payment.caip2 import parse_caip2_chain_id, build_caip2

chain_id = parse_caip2_chain_id("eip155:8453")  # → 8453
caip2    = build_caip2(8453)                     # → "eip155:8453"
```

### Implementing a custom wallet

```python
from conway_sdk.wallet.base import AbstractWallet, ECDSASignature, EIP712Payload

class MyHSMWallet(AbstractWallet):
    @property
    def address(self) -> str:
        return "0x<address>"

    def sign_typed_data(self, payload: EIP712Payload) -> ECDSASignature:
        # Call your HSM or external signer here
        ...

    async def sign_typed_data_async(self, payload: EIP712Payload) -> ECDSASignature:
        # Async variant for I/O-bound signers
        ...
```

---

## Security notes

- **LocalWallet** holds the private key in process memory as raw bytes. Use it
  only with short-lived keys loaded from a secrets manager. For production
  deployments handling real funds, use **KMSWallet** or a hardware security
  module.

- **Never log private keys.** The SDK does not log key material, but callers
  must ensure keys are not passed through logging frameworks.

- **Nonce uniqueness** is enforced per contract by the EIP-3009 standard. In
  multi-instance deployments, use `RedisNonceCache` to prevent concurrent
  instances from producing authorizations with conflicting nonces.

- **EIP-712 domain parameters** (name, version, chainId, verifyingContract)
  must match the on-chain contract exactly. A mismatch causes the server to
  reject the signature.

- **validBefore window**: the SDK enforces a configurable maximum
  (`SdkConfig.max_authorization_window_seconds`, default 24 hours). Servers
  requesting longer windows are refused — a defence against malicious servers
  attempting to obtain long-lived authorizations.

---

## Scope

This SDK provides signing primitives and typed models only.


License

MIT — see [LICENSE](LICENSE).
