peaq-os-sdk 0.0.2__tar.gz

peaq_os_sdk-0.0.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

peaq_os_sdk-0.0.2/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: peaq-os-sdk
+Version: 0.0.2
+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: 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`.
+
+### 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.
+
+Additional capability docs (events, queries, smart accounts, bridging) will be added as the SDK grows.
+
+---
+
+## 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.
+
+`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.

peaq_os_sdk-0.0.2/README.md

@@ -0,0 +1,202 @@
+# 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`.
+
+### 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.
+
+Additional capability docs (events, queries, smart accounts, bridging) will be added as the SDK grows.
+
+---
+
+## 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.
+
+`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.