Metadata-Version: 2.4
Name: pinely-sdk
Version: 0.1.0b1
Summary: PINELY Python SDK: EIP-712 signing and HTTP 402 payments for autonomous machines on Robinhood Chain
Author: PINELY Engineering
License-Expression: MIT
Project-URL: Homepage, https://github.com/pinely-dev/pinely/tree/main/sdk-python#readme
Project-URL: Issues, https://github.com/pinely-dev/pinely/issues
Project-URL: Source, https://github.com/pinely-dev/pinely
Keywords: pinely,depin,robinhood-chain,erc-4337,x402,eip-712,web3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: web3<9,>=7.0.0
Requires-Dist: eth-account<1,>=0.13.1
Requires-Dist: requests<3,>=2.31.0
Dynamic: license-file

# PINELY Python SDK

Python package for autonomous machine finance on Robinhood Chain (testnet `46630`, mainnet `4663`). It implements
the same signing and payment flow as the TypeScript SDK (`@pinely-protocol/sdk`), and produces identical machine
IDs and signatures for identical inputs. It is a **subset** of the TypeScript API, see [Limitations](#limitations).

- Machine key store abstraction (`DevKeyStore`, `KeyStore`).
- EIP-712 signing for revenue swaps (`SwapIntent`) and HTTP 402 payments (`Payment402Intent`).
- `hookData` encoding for the PinelyHook (Stage 2).

## Install

This is a beta release (`0.1.0b1`). While it is the only release, a plain install picks it up:

```bash
pip install pinely-sdk
```

Once a stable release exists, pip skips pre-releases unless you pass `--pre`, so use `pip install --pre pinely-sdk`
to keep following the beta channel.

Supported dependency ranges: `web3` 7.0 to 8.x, `eth-account` 0.13.1 or newer, `requests` 2.31 or newer. The
test suite was run on Python 3.12 with both the lowest and the highest of these combinations.

From a clone of the repository (development):

```bash
pip install -e sdk-python
```

## Usage

```python
from pinely_sdk import Pinely

pinely = Pinely.connect(
    private_key="0x...",
    chain_id=46630,
    registry_address="0x...",  # MachineRegistry, from the deployment address book
    stablecoin_address="0x...",  # canonical stablecoin, from the official Robinhood Chain documentation
    paymaster_address="0x...",  # PinelyPaymaster, required for payments
)
machine = pinely.machines.create(name="autonomous-delivery-01", operator="0x...")

result = machine.pay(
    "https://facilitator.example/v1/charge/dock-001",
    max_amount=250_000,  # 0.25 stablecoin (6 decimals): an upper bound, the challenge amount is what is paid
    facilitator_url="https://facilitator.example",
)
```

## Behaviour you can rely on

- **No default addresses and no default network.** A missing address or an unsupported chain raises.
- **Payments are never simulated.** Without `facilitator_url`, with a 402 challenge for another asset,
  network or a larger amount, or without a Facilitator confirmation carrying a transaction hash and an
  access token, the result is `failed`.
- **Never signs blindly.** The prepared UserOperation is rebuilt and compared field by field (recipient,
  amount, token, paymaster, gas, fee cap) before its hash is signed.
- **Swaps need Stage 2.** `prepare_swap` raises until a `hook_address` is configured.
- **Replay isolation.** The domains are `PINELY` and `PINELYFacilitator`, bound to the chain id. Tests assert
  digests identical to the TypeScript SDK and the contract's type hash, so signatures from any earlier
  deployment never verify.

## Limitations

This beta covers signing, hashing and the HTTP 402 payment flow. Compared with the TypeScript SDK it does **not**
provide:

- **A hardware key store.** `Pinely.connect()` takes a private key and always uses `DevKeyStore`, an in-memory key
  for development. Do not use it for a key that controls real funds on production hardware.
- **On-chain reads.** There is no `rpc_url`, so there is no machine info lookup and no kill-switch (`isFrozen`) check.
- **Transaction builders** for freeze, unfreeze, policy changes and surplus sweeping.

The SDK is not externally audited.

## Tests

```bash
python -m unittest discover -s sdk-python/tests -t sdk-python
```
