pinely-sdk 0.1.0b1__py3-none-any.whl

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/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,
+        )

pinely_sdk/eip712.py

@@ -0,0 +1,108 @@
+"""EIP-712 typing, hashing, and encoding utilities for PINELY on Robinhood Chain.
+
+The type definitions here must stay identical to the TypeScript SDK (`sdk/src/utils/eip712.ts`) and to
+the on-chain typehash in `PinelyHook.sol`. A golden-digest test in `tests/` enforces that parity.
+"""
+
+from typing import Any, Dict
+from eth_abi import encode
+from web3 import Web3
+
+
+_EIP712_DOMAIN = [
+    {"name": "name", "type": "string"},
+    {"name": "version", "type": "string"},
+    {"name": "chainId", "type": "uint256"},
+    {"name": "verifyingContract", "type": "address"},
+]
+
+SWAP_INTENT_TYPES = {
+    "EIP712Domain": _EIP712_DOMAIN,
+    "SwapIntent": [
+        {"name": "machineId", "type": "bytes32"},
+        {"name": "poolId", "type": "bytes32"},
+        {"name": "tokenIn", "type": "address"},
+        {"name": "tokenOut", "type": "address"},
+        {"name": "amountIn", "type": "uint256"},
+        {"name": "minAmountOut", "type": "uint256"},
+        {"name": "nonce", "type": "uint256"},
+        # uint64 like the contract's SWAP_INTENT_TYPEHASH. A uint256 here would produce a different
+        # type hash and the on-chain signature check would always fail.
+        {"name": "deadline", "type": "uint64"},
+        {"name": "chainId", "type": "uint256"},
+    ],
+}
+
+PAYMENT_402_TYPES = {
+    "EIP712Domain": _EIP712_DOMAIN,
+    "Payment402Intent": [
+        {"name": "machineId", "type": "bytes32"},
+        {"name": "resource", "type": "string"},
+        {"name": "amountStable", "type": "uint256"},
+        {"name": "nonce", "type": "uint256"},
+        {"name": "deadline", "type": "uint64"},
+    ],
+}
+
+
+def get_pinely_domain(verifying_contract: str, chain_id: int) -> Dict[str, Any]:
+    """Returns the canonical PINELY Hook EIP-712 domain."""
+    return {
+        "name": "PINELY",
+        "version": "1",
+        "chainId": chain_id,
+        "verifyingContract": Web3.to_checksum_address(verifying_contract),
+    }
+
+
+def get_pinely_facilitator_domain(verifying_contract: str, chain_id: int) -> Dict[str, Any]:
+    """Returns the canonical PINELY Facilitator (HTTP 402) EIP-712 domain."""
+    return {
+        "name": "PINELYFacilitator",
+        "version": "1",
+        "chainId": chain_id,
+        "verifyingContract": Web3.to_checksum_address(verifying_contract),
+    }
+
+
+def compute_machine_id(account: str) -> str:
+    """Computes the canonical machineId: keccak256(abi.encode(account))."""
+    encoded = encode(["address"], [Web3.to_checksum_address(account)])
+    return Web3.to_hex(Web3.keccak(encoded))
+
+
+def compute_pool_id(currency0: str, currency1: str, fee: int, tick_spacing: int, hooks: str) -> str:
+    """Computes the canonical Uniswap v4 PoolId: keccak256(abi.encode(PoolKey))."""
+    encoded = encode(
+        ["address", "address", "uint24", "int24", "address"],
+        [
+            Web3.to_checksum_address(currency0),
+            Web3.to_checksum_address(currency1),
+            fee,
+            tick_spacing,
+            Web3.to_checksum_address(hooks),
+        ],
+    )
+    return Web3.to_hex(Web3.keccak(encoded))
+
+
+def encode_hook_data(intent: Dict[str, Any], signature: str) -> str:
+    """Encodes hookData: abi.encode(SwapIntent intent, bytes signature)."""
+    intent_tuple = (
+        bytes.fromhex(intent["machineId"][2:] if intent["machineId"].startswith("0x") else intent["machineId"]),
+        bytes.fromhex(intent["poolId"][2:] if intent["poolId"].startswith("0x") else intent["poolId"]),
+        Web3.to_checksum_address(intent["tokenIn"]),
+        Web3.to_checksum_address(intent["tokenOut"]),
+        int(intent["amountIn"]),
+        int(intent["minAmountOut"]),
+        int(intent["nonce"]),
+        int(intent["deadline"]),
+        int(intent["chainId"]),
+    )
+    sig_bytes = bytes.fromhex(signature[2:] if signature.startswith("0x") else signature)
+
+    # deadline is uint64 in the Solidity struct; the ABI encoding pads it to 32 bytes, so the encoded
+    # bytes are identical to a uint256 here. The tuple type still mirrors the struct exactly.
+    tuple_type = "(bytes32,bytes32,address,address,uint256,uint256,uint256,uint64,uint256)"
+    encoded = encode([tuple_type, "bytes"], [intent_tuple, sig_bytes])
+    return Web3.to_hex(encoded)

pinely_sdk/keystore.py

@@ -0,0 +1,55 @@
+"""Keystore abstraction for PINELY hardware & autonomous machines."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+from eth_account import Account
+from eth_account.messages import encode_defunct, encode_typed_data
+
+
+class KeyStore(ABC):
+    """Abstract keystore interface for machine private keys."""
+
+    @property
+    @abstractmethod
+    def address(self) -> str:
+        """Returns the checksum Ethereum address of the signer."""
+        pass
+
+    @abstractmethod
+    def sign_message(self, message: bytes) -> str:
+        """Signs an arbitrary message using EIP-191 personal sign."""
+        pass
+
+    @abstractmethod
+    def sign_typed_data(self, full_message: Dict[str, Any]) -> str:
+        """Signs an EIP-712 structured typed data payload."""
+        pass
+
+
+class DevKeyStore(KeyStore):
+    """
+    In-memory developer keystore.
+    WARNING: For local development and testing only. Do not use on production hardware!
+    """
+
+    def __init__(self, private_key: str) -> None:
+        if private_key.startswith("0x"):
+            self._account = Account.from_key(private_key)
+        else:
+            self._account = Account.from_key(f"0x{private_key}")
+
+    @property
+    def address(self) -> str:
+        return self._account.address
+
+    def sign_message(self, message: bytes) -> str:
+        encoded = encode_defunct(message)
+        signed = self._account.sign_message(encoded)
+        sig = signed.signature.hex()
+        return f"0x{sig}" if not sig.startswith("0x") else sig
+
+    def sign_typed_data(self, full_message: Dict[str, Any]) -> str:
+        encoded = encode_typed_data(full_message=full_message)
+        signed = self._account.sign_message(encoded)
+        sig = signed.signature.hex()
+        return f"0x{sig}" if not sig.startswith("0x") else sig

pinely_sdk/userop.py

@@ -0,0 +1,203 @@
+"""ERC-4337 v0.7 UserOperation helpers (parity with `sdk/src/utils/userop.ts`).
+
+The machine must never sign a UserOperation it has not checked. `verify_prepared_settlement` rebuilds the
+expected call data from the payment requirements the machine itself validated and recomputes the
+`userOpHash`, so a facilitator cannot slip in another recipient, a larger amount, a different paymaster or
+inflated gas. Golden hashes in `tests/` pin this module to the TypeScript SDK byte for byte.
+"""
+
+from typing import Any, Dict, Optional
+
+from eth_abi import encode
+from web3 import Web3
+
+#: Canonical ERC-4337 EntryPoint v0.7 (deterministic address). Present on Robinhood Chain testnet and mainnet.
+ENTRY_POINT_V07 = "0x0000000071727De22E5E9d8BAf0edAc6f37da032"
+
+# Static gas parameters (placeholders): production must use the bundler's estimate. Both SDKs pin the same
+# values, so any deviation proposed by a facilitator is refused.
+# verificationGasLimit (150,000) and callGasLimit (100,000), packed
+SETTLEMENT_ACCOUNT_GAS_LIMITS = "0x000000000000000000000000000249f0000000000000000000000000000186a0"
+# maxPriorityFeePerGas (0) and maxFeePerGas (0.1 gwei), packed. Robinhood Chain reports a priority fee of 0 and a
+# base fee of 0.01 to 0.02 gwei, so the ceiling is 5 to 10 times the base fee. The previous 2 gwei made the
+# prefund (450,000 gas) about $2.70 at an ETH price of $3,000, above the Paymaster's default cost cap, so every
+# UserOperation would have been refused. Replace these with the bundler's estimate once a bundler is chosen.
+SETTLEMENT_GAS_FEES = "0x0000000000000000000000000000000000000000000000000000000005f5e100"
+SETTLEMENT_PRE_VERIFICATION_GAS = 50_000
+# paymaster verificationGasLimit (100,000) and postOpGasLimit (50,000), 16 bytes each
+_PAYMASTER_GAS_SUFFIX = "000000000000000000000000000186a0" + "0000000000000000000000000000c350"
+
+#: Facilitator fee cap a machine accepts by default: 1.00% of the payment.
+DEFAULT_MAX_FEE_BPS = 100
+
+
+def _selector(signature: str) -> bytes:
+    return Web3.keccak(text=signature)[:4]
+
+
+def _transfer(to: str, amount: int) -> bytes:
+    return _selector("transfer(address,uint256)") + encode(
+        ["address", "uint256"], [Web3.to_checksum_address(to), amount]
+    )
+
+
+def _hex(data: bytes) -> str:
+    return "0x" + data.hex()
+
+
+def _bytes(value: str) -> bytes:
+    return bytes.fromhex(value[2:] if value.startswith("0x") else value)
+
+
+def _paymaster_and_data(paymaster: str) -> str:
+    return "0x" + _bytes(Web3.to_checksum_address(paymaster)).hex() + _PAYMASTER_GAS_SUFFIX
+
+
+def build_settlement_call_data(
+    stablecoin: str,
+    merchant: str,
+    amount: int,
+    fee_recipient: Optional[str] = None,
+    fee_amount: int = 0,
+) -> str:
+    """`PinelyAccount.execute` for one stablecoin transfer, or `executeBatch` when a fee is paid in the same
+    operation. `amount` is what the merchant receives."""
+    token = Web3.to_checksum_address(stablecoin)
+    if fee_recipient and fee_amount > 0:
+        body = encode(
+            ["address[]", "uint256[]", "bytes[]"],
+            [
+                [token, token],
+                [0, 0],
+                [_transfer(merchant, amount), _transfer(fee_recipient, fee_amount)],
+            ],
+        )
+        return _hex(_selector("executeBatch(address[],uint256[],bytes[])") + body)
+
+    body = encode(["address", "uint256", "bytes"], [token, 0, _transfer(merchant, amount)])
+    return _hex(_selector("execute(address,uint256,bytes)") + body)
+
+
+def build_settlement_user_op(
+    sender: str,
+    nonce: int,
+    stablecoin: str,
+    merchant: str,
+    amount: int,
+    paymaster: str,
+    fee_recipient: Optional[str] = None,
+    fee_amount: int = 0,
+) -> Dict[str, Any]:
+    """Builds the (unsigned) UserOperation that settles one x402 payment, in serialized form."""
+    return {
+        "sender": Web3.to_checksum_address(sender),
+        "nonce": hex(nonce),
+        "initCode": "0x",
+        "callData": build_settlement_call_data(stablecoin, merchant, amount, fee_recipient, fee_amount),
+        "accountGasLimits": SETTLEMENT_ACCOUNT_GAS_LIMITS,
+        "preVerificationGas": hex(SETTLEMENT_PRE_VERIFICATION_GAS),
+        "gasFees": SETTLEMENT_GAS_FEES,
+        "paymasterAndData": _paymaster_and_data(paymaster),
+        "signature": "0x",
+    }
+
+
+def get_user_op_hash(op: Dict[str, Any], entry_point: str, chain_id: int) -> str:
+    """EntryPoint v0.7 `getUserOpHash`. The signature is not part of the hash."""
+    packed = Web3.keccak(
+        encode(
+            ["address", "uint256", "bytes32", "bytes32", "bytes32", "uint256", "bytes32", "bytes32"],
+            [
+                Web3.to_checksum_address(op["sender"]),
+                int(op["nonce"], 16),
+                Web3.keccak(_bytes(op["initCode"])),
+                Web3.keccak(_bytes(op["callData"])),
+                _bytes(op["accountGasLimits"]),
+                int(op["preVerificationGas"], 16),
+                _bytes(op["gasFees"]),
+                Web3.keccak(_bytes(op["paymasterAndData"])),
+            ],
+        )
+    )
+    return Web3.to_hex(
+        Web3.keccak(
+            encode(
+                ["bytes32", "address", "uint256"],
+                [packed, Web3.to_checksum_address(entry_point), chain_id],
+            )
+        )
+    )
+
+
+def _same(a: Any, b: Any) -> bool:
+    return str(a).lower() == str(b).lower()
+
+
+def verify_prepared_settlement(
+    prepared: Dict[str, Any],
+    *,
+    sender: str,
+    stablecoin: str,
+    merchant: str,
+    gross_amount: int,
+    paymaster: str,
+    entry_point: str,
+    chain_id: int,
+    max_fee_bps: int = DEFAULT_MAX_FEE_BPS,
+) -> Dict[str, Any]:
+    """Checks a prepared UserOperation field by field and returns it only if the machine can safely sign
+    it. Raises `ValueError` with a descriptive message otherwise. Nothing here trusts the facilitator."""
+    try:
+        op = prepared["userOp"]
+        for key in (
+            "sender", "nonce", "initCode", "callData", "accountGasLimits",
+            "preVerificationGas", "gasFees", "paymasterAndData", "signature",
+        ):
+            if not isinstance(op.get(key), str):
+                raise ValueError(f"UserOperation.{key} is missing")
+        int(op["nonce"], 16)
+        int(op["preVerificationGas"], 16)
+        declared_hash = str(prepared["userOpHash"])
+        declared_entry_point = str(prepared["entryPoint"])
+        declared_chain = int(prepared["chainId"])
+    except (KeyError, TypeError, ValueError) as e:
+        raise ValueError(f"Malformed prepared settlement ({e})") from e
+
+    if not _same(declared_entry_point, entry_point):
+        raise ValueError("EntryPoint differs from the expected canonical EntryPoint")
+    if declared_chain != chain_id:
+        raise ValueError("UserOperation is for another network")
+    if not _same(op["sender"], sender):
+        raise ValueError("UserOperation is not sent from the machine account")
+    if op["initCode"] != "0x":
+        raise ValueError("UserOperation deploys code (initCode must be empty)")
+    if op["signature"] != "0x":
+        raise ValueError("UserOperation must be unsigned")
+    if not _same(op["paymasterAndData"], _paymaster_and_data(paymaster)):
+        raise ValueError("UserOperation uses an unexpected paymaster or paymaster gas")
+    if (
+        not _same(op["accountGasLimits"], SETTLEMENT_ACCOUNT_GAS_LIMITS)
+        or not _same(op["gasFees"], SETTLEMENT_GAS_FEES)
+        or int(op["preVerificationGas"], 16) != SETTLEMENT_PRE_VERIFICATION_GAS
+    ):
+        raise ValueError("UserOperation gas parameters differ from the expected values")
+
+    # Facilitator fee: bounded, and the machine still pays exactly the agreed gross amount.
+    fee = int(prepared.get("facilitatorFee") or 0)
+    if fee < 0 or fee >= gross_amount:
+        raise ValueError("Facilitator fee is out of range")
+    if fee * 10_000 > gross_amount * max_fee_bps:
+        raise ValueError("Facilitator fee exceeds the accepted maximum")
+    fee_recipient = prepared.get("feeRecipient")
+    if fee > 0 and not (fee_recipient and Web3.is_address(fee_recipient)):
+        raise ValueError("Facilitator fee has no valid recipient")
+
+    expected_call_data = build_settlement_call_data(
+        stablecoin, merchant, gross_amount - fee, fee_recipient if fee > 0 else None, fee
+    )
+    if not _same(op["callData"], expected_call_data):
+        raise ValueError("UserOperation call data does not match the agreed payment")
+
+    if not _same(get_user_op_hash(op, entry_point, chain_id), declared_hash):
+        raise ValueError("userOpHash does not match the UserOperation")
+    return op

pinely_sdk-0.1.0b1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+pinely_sdk/__init__.py,sha256=6Chn2jOjGsRH4S8ICT5Zhh78yUKOXA2nmmw7frY-mhA,1050
+pinely_sdk/client.py,sha256=M_DtUnGOMPK4N1UgE0mhfyfixrKnldyo2aPxQujGo1E,16620
+pinely_sdk/eip712.py,sha256=qj_Lyj2_MVQurExFVJnMGnQy9ppArXxmtdz2tXBQDY0,4302
+pinely_sdk/keystore.py,sha256=L1hUBlOfFtAli3EEWSAC004U16hMeI4BHLYcdAJMtuA,1853
+pinely_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pinely_sdk/userop.py,sha256=fe9G7S3zZ57efvHcHWad7kDWa_Nd09XWYCg5LgpUoR0,8763
+pinely_sdk-0.1.0b1.dist-info/licenses/LICENSE,sha256=TL6tlUPS0w4H8fyy2wMaPc0sZYppA8e-9GamjXqh_kU,1097
+pinely_sdk-0.1.0b1.dist-info/METADATA,sha256=zd52noYEWdwfcYtzj11SU1KrV532eji2_p0uzz8BZn0,4520
+pinely_sdk-0.1.0b1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pinely_sdk-0.1.0b1.dist-info/top_level.txt,sha256=Q8mkrAdPPD0qPQ7WKJ9ELV1ayjRtxY2LQCEcjMlspqs,11
+pinely_sdk-0.1.0b1.dist-info/RECORD,,

pinely_sdk-0.1.0b1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pinely_sdk-0.1.0b1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+pinely_sdk