Metadata-Version: 2.4
Name: peaq-os-sdk
Version: 0.1.0
Summary: Python SDK for peaqOS, the operating system for the machine economy — on-chain identity, credit rating, and omnichain infrastructure for robots and machines.
Author-email: peaqOS <info@peaq.xyz>
License: Apache-2.0
Project-URL: Homepage, https://www.peaq.xyz
Project-URL: Documentation, https://docs.peaq.xyz
Project-URL: Repository, https://github.com/peaqnetwork/peaq-os-sdk-py
Project-URL: Issues, https://github.com/peaqnetwork/peaq-os-sdk-py/issues
Keywords: peaq,peaqos,peaq-os,machine-economy,depin,robotics,ai-agents,blockchain,omnichain,peaqid,did,machine-nft,machine-tokenization,machine-credit-rating,mcr,sdk,python
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: web3>=6.0
Requires-Dist: eth-account
Requires-Dist: requests
Provides-Extra: ows
Requires-Dist: open-wallet-standard>=1.3.2; extra == "ows"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

# peaq-os-sdk

Python SDK for the peaqOS protocol. Provides a typed wrapper around the peaq on-chain capabilities so integrators can onboard machines, submit events, mint NFTs, and query credit ratings without writing raw `web3.py` boilerplate.

---

## Install

```bash
pip install peaq-os-sdk
```

Dependencies installed automatically: `web3`, `eth-account`, `requests`.

For OWS wallet management (optional):

```bash
pip install peaq-os-sdk[ows]
```

### Requirements

- Python `>= 3.10`
- A peaq RPC endpoint
- A funded wallet for the proxy operator (or for the machine itself, in self-managed mode)

---

## Quick start

```python
from peaq_os_sdk import PeaqosClient

client = PeaqosClient(
    rpc_url="https://peaq.api.onfinality.io/public",
    private_key="0xYOUR_PRIVATE_KEY",
    identity_registry="0x...",
    identity_staking="0x...",
    event_registry="0x...",
    machine_nft="0x...",
    did_registry="0x...",
    batch_precompile="0x...",
)

print("signer address:", client.address)
```

`PeaqosClient` is the only class consumers instantiate. All feature methods hang off it. The constructor performs synchronous validation and wires up the underlying `Web3` provider + signing account — no network I/O is issued at construction time.

[**Read More here >>**](docs/01_QUICK_START.md)

---

## MCR queries

Three read-only methods talk to the off-chain MCR API server at `client.api_url` (override via the `api_url` kwarg or `PEAQOS_MCR_API_URL`; defaults to `http://127.0.0.1:8000`). All three validate the DID prefix (`did:peaq:0x…`) locally and share a single `requests.Session` for connection pooling.

| Method | HTTP endpoint | Returns |
|---|---|---|
| `client.query_mcr(did)` | `GET /mcr/{did}` | `MCRResponse` TypedDict |
| `client.query_machine(did)` | `GET /machine/{did}` | `MachineProfileResponse` (NFT metadata JSON v1.0 as `dict[str, Any]`) |
| `client.query_operator_machines(did)` | `GET /operator/{did}/machines` | `OperatorMachinesResponse` |

`MCRResponse`:

```python
{
    "did": str,
    "machine_id": int,
    "mcr_score": int | None,    # 0–100, None if Provisioned
    "mcr": str,                 # "AAA" | "AA" | "A" | "BBB" | "BB" | "B" | "NR" | "Provisioned"
    "bond_status": str,         # "bonded" | "unbonded"
    "negative_flag": bool,      # active negative event flag
    "event_count": int,
    "revenue_event_count": int,
    "activity_event_count": int,
    "revenue_trend": str,       # "up" | "stable" | "down" | "insufficient"
    "total_revenue": float,
    "average_revenue_per_event": float,
    "last_updated": int | None,
}
```

`OperatorMachinesResponse` carries `operator_did`, a `machines` list of `{did, machine_id, mcr_score, mcr, negative_flag}` entries, and a `pagination` object. `MachineProfileResponse` returns structured NFT metadata with a validated `peaqos` sub-object. Every failure path is an `ApiError` with a stable `.code` (`NOT_FOUND`, `SERVICE_UNAVAILABLE`, `SERVER_ERROR`, `HTTP_ERROR`, `BAD_RESPONSE`, `TIMEOUT`, `NETWORK_ERROR`). See [docs/03_QUERIES.md](docs/03_QUERIES.md) for the full endpoint and error reference.

---

## Smart account deployment

ERC-4337 smart accounts are provisioned via the `MachineAccountFactory` contract using CREATE2 — the deployed address is deterministic from `(owner, machine, daily_limit, salt)`, so the same tuple always resolves to the same address.

| Method | On-chain | Returns |
|---|---|---|
| `client.get_smart_account_address(owner, machine, daily_limit, salt)` | view call — no gas | predicted address |
| `client.deploy_smart_account(owner, machine, daily_limit, salt)` | `createAccount` tx | deployed address |

Because CREATE2 is deterministic, `predicted == deployed` for the same inputs — callers can preview the address, pre-fund it, or display it in a UI before paying gas. Configure the factory address via the optional `machine_account_factory` kwarg on `PeaqosClient` or the `MACHINE_ACCOUNT_FACTORY_ADDRESS` env var. See [docs/04_SMART_ACCOUNTS.md](docs/04_SMART_ACCOUNTS.md) for parameter rules and receipt-decoding error codes.

---

## Cross-chain NFT bridging

Machine NFTs move between peaq and Base over LayerZero v2. Two chains are recognised today; direction is inferred from the `source` / `destination` arguments.

| Chain | `SUPPORTED_CHAINS` id | `LAYERZERO_EIDS` |
|---|---|---|
| `"peaq"` | 3338 | **30302** |
| `"base"` | 8453 | **30184** |

| Direction | Source contract | Effect | `dstEid` |
|---|---|---|---|
| peaq → base | `MachineNFTAdapter` on peaq | NFT locked on peaq, minted on Base | `30184` |
| base → peaq | `MachineNFTBase` on Base | NFT burned on Base, unlocked on peaq | `30302` |

`client.bridge_nft(...)` estimates the LayerZero messaging fee via `quoteSend` **before** broadcasting and attaches that fee as `msg.value` on the actual `send` transaction so the message is correctly paid for. `PeaqosClient.wait_for_bridge_arrival(...)` is a static method (no client instance needed) that polls `MachineNFT.ownerOf(token_id)` on the destination every 10 seconds and returns `True` on arrival or `False` at timeout (default 300 s). See [docs/05_BRIDGE.md](docs/05_BRIDGE.md) for the full walkthrough including `options` handling, Base-source setup, and the complete error-code table.

---

## Documentation

Per-feature deep-dives live under [`docs/`](docs/):

- [**Quick Start**](docs/01_QUICK_START.md) — client initialization, configuration, environment variables, types, exception classes, validation, utilities, and constants.
- [**Machine identity & registration**](docs/02_REGISTRATION.md) — faucet 2FA enrollment, gas-station funding, self-managed and proxy-managed registration. Includes the full faucet error reference and the on-chain revert mapping.
- [**MCR queries**](docs/03_QUERIES.md) — `query_mcr`, `query_machine`, `query_operator_machines`, response shapes, rating tiers, and the full HTTP error-code table.
- [**Smart account deployment**](docs/04_SMART_ACCOUNTS.md) — `deploy_smart_account` and `get_smart_account_address`, CREATE2 determinism, parameter rules, and receipt-decoding error codes.
- [**Cross-chain NFT bridging**](docs/05_BRIDGE.md) — `bridge_nft` direction handling (peaq ↔ Base via LayerZero v2), supported chain IDs and LayerZero EIDs, LayerZero fee estimation, and `wait_for_bridge_arrival` polling semantics.
- [**Event submission**](docs/03_EVENTS.md) — single and batch event submission, pipeline details, limits, hashing, metadata mode, and rate-limiting behavior.
- [**NFT minting & DID attributes**](docs/04_NFT_AND_DID.md) — minting machine NFTs, querying token IDs, writing machine and proxy DID attributes atomically via the Batch precompile. Covers attribute key reference, data visibility options, and the atomic batch guarantee.
- [**OWS wallet lifecycle**](docs/06_WALLET.md) — create, import, list, get, export, and delete encrypted wallets via the Open Wallet Standard. Multi-chain accounts, passphrase management, and vault storage.

---

## Development

```bash
git clone https://github.com/peaqnetwork/peaq-os-sdk-py.git
cd peaq-os-sdk-py
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### Activate `.env` for Testing
```
set -a
source .env
set +a
```

### Quality gates

```bash
ruff check src tests       # lint — zero warnings
black --check src tests    # formatting
mypy src                   # strict type check, zero errors
pytest -q                  # all green
```

The unit tests are hermetic — they mock `Web3` and `requests.Session` with handwritten stubs and never touch the network.

### Optional integration tests

The repo ships an opt-in suite that talks to a real peaq devnet. It is skipped silently in normal `pytest -q` and only runs when the required environment variables are supplied.

**Registration integration suite** ([`tests/integration/registration/test_registration_integration.py`](tests/integration/registration/test_registration_integration.py)) — three end-to-end tests for the self-managed flow, proxy-managed flow, and double-registration revert. Gated behind the `integration` marker plus seven environment variables:

```bash
PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public
PEAQOS_PRIVATE_KEY=0xYOUR_FUNDED_TREASURY_KEY
IDENTITY_REGISTRY_ADDRESS=0xYOUR_DEPLOYED_REGISTRY_ADDRESS
IDENTITY_STAKING_ADDRESS=0xYOUR_DEPLOYED_STAKING_ADDRESS
PEAQOS_OWNER_ADDRESS=5GrwvaEF...
PEAQOS_FAUCET_URL=https://depinstation.peaq.xyz
PEAQOS_2FA_CODE=123456
```

```bash
pytest -m integration tests/integration/
```

See [docs/02_REGISTRATION.md → Integration tests](docs/02_REGISTRATION.md#integration-tests) for the full breakdown of what each test verifies and operational warnings.

**NFT & DID integration suite** ([`tests/integration/nft_did/test_nft_and_did_integration.py`](tests/integration/nft_did/test_nft_and_did_integration.py)) — end-to-end tests for the full NFT lifecycle, atomic DID writes, and atomicity guarantee verification (all-or-nothing batch semantics). Includes 7 tests across minting, token queries, machine DID attributes, proxy DID attributes, and atomic revert scenarios. Requires the same env vars as the registration suite plus:

```bash
EVENT_REGISTRY_ADDRESS=0x...
MACHINE_NFT_ADDRESS=0x...
DID_REGISTRY_ADDRESS=0x0000000000000000000000000000000000000800
BATCH_PRECOMPILE_ADDRESS=0x0000000000000000000000000000000000000805
```

See [docs/04_NFT_AND_DID.md](docs/04_NFT_AND_DID.md) for the full breakdown.

**OWS wallet integration suite** ([`tests/integration/wallet/test_wallet_integration.py`](tests/integration/wallet/test_wallet_integration.py)) — six end-to-end tests for wallet lifecycle (create, list, get, delete), create-export-reimport round-trip, private key import, empty vault, and error paths. Gated behind `PEAQOS_INTEGRATION=1` and requires the `open-wallet-standard` package:

```bash
pip install peaq-os-sdk[ows]
PEAQOS_INTEGRATION=1 pytest -m integration tests/integration/wallet/
```

See [docs/06_WALLET.md](docs/06_WALLET.md) for the full wallet API reference.

`PEAQOS_PRIVATE_KEY` must match `^0x[0-9a-fA-F]{64}$`. **Never commit a real key. Never run the suite against mainnet.**

### Build

```bash
python -m build
```

Produces `dist/peaq_os_sdk-<version>-py3-none-any.whl` and `dist/peaq_os_sdk-<version>.tar.gz` for downstream testing.

## License

See [LICENSE](./LICENSE) for details.
