pinely-sdk 0.1.0b1__tar.gz

pinely_sdk-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PINELY contributors
+
+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.

pinely_sdk-0.1.0b1/PKG-INFO

@@ -0,0 +1,105 @@
+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
+```

pinely_sdk-0.1.0b1/README.md

@@ -0,0 +1,81 @@
+# 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
+```

pinely_sdk-0.1.0b1/pinely_sdk/__init__.py

@@ -0,0 +1,42 @@
+"""PINELY Python SDK — autonomous machine finance on Robinhood Chain."""
+
+from .client import SUPPORTED_CHAIN_IDS, MachineClient, Pinely
+from .eip712 import (
+    PAYMENT_402_TYPES,
+    SWAP_INTENT_TYPES,
+    compute_machine_id,
+    compute_pool_id,
+    encode_hook_data,
+    get_pinely_domain,
+    get_pinely_facilitator_domain,
+)
+from .keystore import DevKeyStore, KeyStore
+from .userop import (
+    ENTRY_POINT_V07,
+    build_settlement_call_data,
+    build_settlement_user_op,
+    get_user_op_hash,
+    verify_prepared_settlement,
+)
+
+__all__ = [
+    "Pinely",
+    "MachineClient",
+    "SUPPORTED_CHAIN_IDS",
+    "KeyStore",
+    "DevKeyStore",
+    "compute_machine_id",
+    "compute_pool_id",
+    "encode_hook_data",
+    "get_pinely_domain",
+    "get_pinely_facilitator_domain",
+    "SWAP_INTENT_TYPES",
+    "PAYMENT_402_TYPES",
+    "ENTRY_POINT_V07",
+    "build_settlement_call_data",
+    "build_settlement_user_op",
+    "get_user_op_hash",
+    "verify_prepared_settlement",
+]
+
+__version__ = "0.1.0b1"

pinely_sdk-0.1.0b1/pinely_sdk/client.py

@@ -0,0 +1,408 @@
+"""Pinely and MachineClient classes for the Python SDK (parity with the TypeScript SDK)."""
+
+import time
+from typing import Any, Dict, Optional
+import requests
+from web3 import Web3
+
+from .eip712 import (
+    PAYMENT_402_TYPES,
+    SWAP_INTENT_TYPES,
+    compute_machine_id,
+    compute_pool_id,
+    encode_hook_data,
+    get_pinely_domain,
+    get_pinely_facilitator_domain,
+)
+from .keystore import DevKeyStore, KeyStore
+from .userop import ENTRY_POINT_V07, verify_prepared_settlement
+
+#: Robinhood Chain testnet and mainnet. Anything else is refused: the SDK never guesses a network.
+SUPPORTED_CHAIN_IDS = (46630, 4663)
+
+_nonce_counter = 0
+
+
+def _generate_monotonic_nonce() -> int:
+    """Generates a microsecond-resolution monotonic nonce preventing collisions."""
+    global _nonce_counter
+    _nonce_counter = (_nonce_counter + 1) % 1000
+    return int(time.time() * 1000000) + _nonce_counter
+
+
+def _require_supported_chain(chain_id: int) -> int:
+    if chain_id not in SUPPORTED_CHAIN_IDS:
+        raise ValueError(
+            f"Unsupported chain id {chain_id} (expected one of {SUPPORTED_CHAIN_IDS})."
+        )
+    return chain_id
+
+
+class MachineClient:
+    """Public interface for a specific PINELY machine device."""
+
+    def __init__(
+        self,
+        machine_id: str,
+        name: str,
+        operator: str,
+        account: str,
+        keystore: KeyStore,
+        registry_address: str,
+        stablecoin_address: str,
+        chain_id: int,
+        hook_address: Optional[str] = None,
+        router_address: Optional[str] = None,
+        paymaster_address: Optional[str] = None,
+        entry_point_address: str = ENTRY_POINT_V07,
+    ) -> None:
+        self.machine_id = machine_id
+        self.name = name
+        self.operator = Web3.to_checksum_address(operator)
+        self.account = Web3.to_checksum_address(account)
+        self.keystore = keystore
+        self.registry_address = Web3.to_checksum_address(registry_address)
+        self.stablecoin_address = Web3.to_checksum_address(stablecoin_address)
+        # PinelyHook and PinelyRouter only exist from Stage 2.
+        self.hook_address = Web3.to_checksum_address(hook_address) if hook_address else None
+        self.router_address = Web3.to_checksum_address(router_address) if router_address else None
+        self.paymaster_address = (
+            Web3.to_checksum_address(paymaster_address) if paymaster_address else None
+        )
+        self.entry_point_address = Web3.to_checksum_address(entry_point_address)
+        self.chain_id = _require_supported_chain(chain_id)
+
+    def _require_hook(self) -> str:
+        if not self.hook_address:
+            raise RuntimeError(
+                f"PinelyHook is not deployed on chain {self.chain_id} (Stage 2). Swaps are unavailable."
+            )
+        return self.hook_address
+
+    def quote_swap(self, token_in: str, amount_in: int) -> Dict[str, Any]:
+        """Estimates the swap output with the Bronze fee tier.
+
+        This is a local estimate: the on-chain tier is not read by the Python SDK.
+        """
+        lp_fee = (amount_in * 3000) // 1_000_000  # Bronze 0.30%
+        protocol_fee = (amount_in * 500) // 1_000_000  # Protocol 0.05%
+        amount_out = amount_in - lp_fee - protocol_fee
+
+        return {
+            "amountIn": amount_in,
+            "amountOut": amount_out,
+            "lpFee": lp_fee,
+            "protocolFee": protocol_fee,
+            "estimatedTier": 0,
+        }
+
+    def prepare_swap(
+        self,
+        token_in: str,
+        amount_in: int,
+        min_amount_out: int,
+        token_out: Optional[str] = None,
+        deadline_seconds: int = 300,
+        nonce: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Prepares a signed EIP-712 SwapIntent and the encoded hookData."""
+        if min_amount_out <= 0:
+            raise ValueError("min_amount_out must be greater than 0 for slippage protection.")
+        hook_address = self._require_hook()
+
+        out_token = token_out or self.stablecoin_address
+        resolved_nonce = nonce if nonce is not None else _generate_monotonic_nonce()
+        deadline = int(time.time()) + deadline_seconds
+
+        token_a = Web3.to_checksum_address(token_in)
+        token_b = Web3.to_checksum_address(out_token)
+
+        c0, c1 = (token_a, token_b) if token_a.lower() < token_b.lower() else (token_b, token_a)
+        pool_id = compute_pool_id(c0, c1, 0x800000, 60, hook_address)
+
+        intent = {
+            "machineId": self.machine_id,
+            "poolId": pool_id,
+            "tokenIn": token_a,
+            "tokenOut": token_b,
+            "amountIn": amount_in,
+            "minAmountOut": min_amount_out,
+            "nonce": resolved_nonce,
+            "deadline": deadline,
+            "chainId": self.chain_id,
+        }
+
+        full_message = {
+            "types": SWAP_INTENT_TYPES,
+            "domain": get_pinely_domain(hook_address, self.chain_id),
+            "primaryType": "SwapIntent",
+            "message": intent,
+        }
+
+        signature = self.keystore.sign_typed_data(full_message)
+        hook_data = encode_hook_data(intent, signature)
+
+        return {
+            "intent": intent,
+            "signature": signature,
+            "hookData": hook_data,
+            "poolKey": {
+                "currency0": c0,
+                "currency1": c1,
+                "fee": 0x800000,
+                "tickSpacing": 60,
+                "hooks": hook_address,
+            },
+        }
+
+    def pay(
+        self,
+        url: str,
+        max_amount: int,
+        facilitator_url: Optional[str] = None,
+        max_fee_bps: int = 100,
+    ) -> Dict[str, Any]:
+        """Executes the HTTP 402 (x402) payment protocol against a Facilitator.
+
+        1. Reads the payment requirements from the resource's HTTP 402 challenge.
+        2. Validates them against what this machine is willing to pay: the asset must be the configured
+           stablecoin, the network must match, and the amount must not exceed `max_amount`.
+        3. Signs an EIP-712 Payment402Intent, asks the Facilitator to prepare the sponsored UserOperation,
+           verifies it field by field, signs its hash with the machine session key and submits it. A
+           UserOperation that pays another recipient, a larger amount, uses another paymaster or inflated gas
+           is never signed.
+
+        Fail-closed: without a Facilitator URL, with an unexpected challenge, or without a Facilitator
+        confirmation carrying both a transaction reference and an access token, the result is `failed`.
+        Payments are never simulated.
+        """
+
+        def fail(error: str, amount: Optional[int] = None) -> Dict[str, Any]:
+            return {"status": "failed", "resource": url, "amountStable": amount, "error": error}
+
+        if not facilitator_url:
+            return fail("facilitator_url is required: payments are never simulated.")
+
+        # 1. HTTP 402 challenge
+        try:
+            challenge = requests.get(url, timeout=30)
+        except Exception as e:  # network failure, timeout, ...
+            return fail(str(e))
+        if challenge.status_code != 402:
+            return fail(f"Resource did not return HTTP 402 (got {challenge.status_code}).")
+        try:
+            body = challenge.json()
+        except ValueError:
+            body = None
+        # A malformed challenge (a JSON list, string or null, or entries that are not objects) must come back
+        # as a failed payment, never as an exception that takes the machine process down.
+        accepts = body.get("accepts") if isinstance(body, dict) else None
+        if not isinstance(accepts, list) or not accepts or not isinstance(accepts[0], dict):
+            return fail("The 402 challenge contains no payment requirements.")
+        accept = accepts[0]
+
+        # 2. Validate the requirements before signing anything
+        asset = str(accept.get("asset") or "")
+        if not asset or asset.lower() != self.stablecoin_address.lower():
+            return fail("The 402 challenge asks for an asset other than the configured stablecoin.")
+        extra = accept.get("extra")
+        raw_chain = extra.get("chainId") if isinstance(extra, dict) else None
+        try:
+            challenge_chain = int(raw_chain) if raw_chain is not None else None
+        except (TypeError, ValueError):
+            challenge_chain = None
+        if challenge_chain != self.chain_id:
+            return fail("The 402 challenge is for a different network.")
+        pay_to = accept.get("payTo")
+        if not pay_to or not Web3.is_address(pay_to):
+            return fail("The 402 challenge has no valid payTo address.")
+        try:
+            amount = int(accept["maxAmountRequired"])
+        except (KeyError, TypeError, ValueError):
+            return fail("The 402 challenge has no valid amount.")
+        if amount <= 0 or amount > max_amount:
+            return fail("The 402 challenge asks for more than max_amount.", amount)
+
+        # 3. What the machine independently expects for the sponsored UserOperation
+        if not self.paymaster_address:
+            return fail("PinelyPaymaster address is required to verify the sponsored UserOperation.", amount)
+
+        # 4. Sign the payment intent
+        intent = {
+            "machineId": self.machine_id,
+            "resource": accept.get("resource") or url,
+            "amountStable": amount,
+            "nonce": _generate_monotonic_nonce(),
+            "deadline": int(time.time()) + 300,
+        }
+
+        full_message = {
+            "types": PAYMENT_402_TYPES,
+            # The registry is deployed in Stage 1, so it is always available as the verifying contract.
+            "domain": get_pinely_facilitator_domain(self.registry_address, self.chain_id),
+            "primaryType": "Payment402Intent",
+            "message": intent,
+        }
+        signature = self.keystore.sign_typed_data(full_message)
+
+        base = facilitator_url.rstrip("/")
+        request = {
+            "intent": {
+                "machineId": intent["machineId"],
+                "resource": intent["resource"],
+                "amountStable": str(amount),
+                "nonce": str(intent["nonce"]),
+                "deadline": str(intent["deadline"]),
+            },
+            "signature": signature,
+            "machineAccount": self.account,
+            "merchantAddress": Web3.to_checksum_address(pay_to),
+        }
+
+        try:
+            # 5. The facilitator builds the unsigned UserOperation
+            prepare_resp = requests.post(f"{base}/v1/settle/prepare", json=request, timeout=30)
+            if prepare_resp.status_code != 200:
+                return fail(
+                    f"Facilitator returned HTTP {prepare_resp.status_code} while preparing", amount
+                )
+            prepared = prepare_resp.json()
+
+            # 6. Never sign blindly: rebuild what the UserOperation must contain and compare
+            try:
+                verify_prepared_settlement(
+                    prepared,
+                    sender=self.account,
+                    stablecoin=self.stablecoin_address,
+                    merchant=pay_to,
+                    gross_amount=amount,
+                    paymaster=self.paymaster_address,
+                    entry_point=self.entry_point_address,
+                    chain_id=self.chain_id,
+                    max_fee_bps=max_fee_bps,
+                )
+            except ValueError as e:
+                return fail(f"Refused to sign the UserOperation: {e}", amount)
+
+            # 7. PinelyAccount.validateUserOp recovers the signer from personal_sign over the raw hash
+            user_op_signature = self.keystore.sign_message(bytes.fromhex(prepared["userOpHash"][2:]))
+
+            # 8. Submit; the facilitator confirms on-chain before it answers
+            resp = requests.post(
+                f"{base}/v1/settle",
+                json={**request, "userOp": prepared["userOp"], "userOpSignature": user_op_signature},
+                timeout=60,
+            )
+        except Exception as e:  # network failure, timeout, malformed JSON ...
+            return fail(str(e), amount)
+
+        if resp.status_code != 200:
+            return fail(f"Facilitator returned HTTP {resp.status_code}", amount)
+
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {}
+        if not isinstance(data, dict):
+            data = {}
+        if data.get("status") != "settled" or not data.get("txHash") or not data.get("accessToken"):
+            return fail("Facilitator response did not confirm a settled payment.", amount)
+
+        return {
+            "status": "settled",
+            "resource": url,
+            "amountStable": amount,
+            "txHash": data["txHash"],
+            "accessToken": data["accessToken"],
+        }
+
+
+class MachineManager:
+    """Factory helper for managing Pinely machines."""
+
+    def __init__(self, client: "Pinely") -> None:
+        self._client = client
+
+    def create(
+        self,
+        name: str,
+        operator: str,
+        account: Optional[str] = None,
+    ) -> MachineClient:
+        """Creates a MachineClient.
+
+        When `account` is omitted the signer address is used as the account, which is a development
+        shortcut. Production machines pass the smart-account address predicted by the factory.
+        """
+        account_addr = account or self._client.keystore.address
+        machine_id = compute_machine_id(account_addr)
+
+        return MachineClient(
+            machine_id=machine_id,
+            name=name,
+            operator=operator,
+            account=account_addr,
+            keystore=self._client.keystore,
+            registry_address=self._client.registry_address,
+            stablecoin_address=self._client.stablecoin_address,
+            chain_id=self._client.chain_id,
+            hook_address=self._client.hook_address,
+            router_address=self._client.router_address,
+            paymaster_address=self._client.paymaster_address,
+            entry_point_address=self._client.entry_point_address,
+        )
+
+
+class Pinely:
+    """Main client class for PINELY on Robinhood Chain.
+
+    There are no default addresses: the registry and stablecoin addresses must be passed explicitly, taken
+    from the deployment address book (`shared/contracts`) and the official Robinhood Chain documentation.
+    """
+
+    def __init__(
+        self,
+        keystore: KeyStore,
+        chain_id: int,
+        registry_address: str,
+        stablecoin_address: str,
+        hook_address: Optional[str] = None,
+        router_address: Optional[str] = None,
+        paymaster_address: Optional[str] = None,
+        entry_point_address: str = ENTRY_POINT_V07,
+    ) -> None:
+        self.keystore = keystore
+        self.chain_id = _require_supported_chain(chain_id)
+        self.registry_address = Web3.to_checksum_address(registry_address)
+        self.stablecoin_address = Web3.to_checksum_address(stablecoin_address)
+        self.hook_address = Web3.to_checksum_address(hook_address) if hook_address else None
+        self.router_address = Web3.to_checksum_address(router_address) if router_address else None
+        self.paymaster_address = (
+            Web3.to_checksum_address(paymaster_address) if paymaster_address else None
+        )
+        self.entry_point_address = Web3.to_checksum_address(entry_point_address)
+        self.machines = MachineManager(self)
+
+    @classmethod
+    def connect(
+        cls,
+        private_key: str,
+        chain_id: int,
+        registry_address: str,
+        stablecoin_address: str,
+        hook_address: Optional[str] = None,
+        router_address: Optional[str] = None,
+        paymaster_address: Optional[str] = None,
+        entry_point_address: str = ENTRY_POINT_V07,
+    ) -> "Pinely":
+        keystore = DevKeyStore(private_key)
+        return cls(
+            keystore=keystore,
+            chain_id=chain_id,
+            registry_address=registry_address,
+            stablecoin_address=stablecoin_address,
+            hook_address=hook_address,
+            router_address=router_address,
+            paymaster_address=paymaster_address,
+            entry_point_address=entry_point_address,
+        )