polynode 0.14.0__tar.gz → 0.14.1__tar.gz

{polynode-0.14.0 → polynode-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: polynode
-Version: 0.14.0
+Version: 0.14.1
 Summary: Python SDK for the Polynode real-time prediction market data platform
 Project-URL: Homepage, https://polynode.dev
 Project-URL: Documentation, https://docs.polynode.dev
@@ -36,7 +36,9 @@ Description-Content-Type: text/markdown
 
 Python SDK for the [Polynode](https://polynode.dev) real-time prediction market data platform.
 
-**New in v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
+**New in v0.14.1:** Every prepared user-owned order exposes its canonical V2 exchange `order_hash` before submission. This is the exact CLOB/open-order ID and fill `order_hash`; deposit-wallet orders hash the standard inner `Order`, not the POLY_1271 wallet-signing wrapper. Record it before the network attempt so timeouts can be reconciled without risking a duplicate.
+
+**In v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
 
 **In v0.13.0:** Trading added explicit `user_owned` execution. Existing builder mode remains the default; opted-in wallets use zero builder attribution, one wallet-ownership authorization, and strict wallet-bound gasless credentials. Builder credentials and nonzero builder codes fail closed in this mode. EOA-controlled Safe and deposit wallets are supported; legacy Magic/proxy wallets are intentionally excluded from the first release.
 
@@ -536,29 +538,82 @@ const result = await fetch("/api/orders/submit", {
 }).then((response) => response.json());
 ```
 
-On the backend, atomically take the prepared object from session state, then validate and submit it:
+On the backend, atomically take the prepared object from session state, durably record the deterministic order identity, then validate and submit it:
 
 ```python
-async def submit_order(trader, browser_result, prepared_orders):
+async def submit_order(trader, browser_result, prepared_orders, attempts):
     # `take_once` must delete atomically so two workers cannot submit the same request.
     prepared = await prepared_orders.take_once(browser_result.request_id)
     if prepared is None:
         raise ValueError("Unknown or already-used signing request")
 
-    result = await trader.submit_prepared_user_owned_order(
-        prepared,
+    order_hash = prepared.order_hash
+    # This durable, idempotent write must commit before submission starts.
+    await attempts.create_once(
+        order_hash=order_hash,
         request_id=browser_result.request_id,
-        address=browser_result.address,
-        signature=browser_result.signature,
+        wallet=prepared.signing_request.address,
+        token_id=prepared.signing_request.order["tokenId"],
+        side=prepared.signing_request.order["side"],
+        status="submitting",
     )
-    return {
-        "success": result.success,
-        "orderId": result.order_id,
-        "error": result.error,
-    }
+
+    try:
+        result = await trader.submit_prepared_user_owned_order(
+            prepared,
+            request_id=browser_result.request_id,
+            address=browser_result.address,
+            signature=browser_result.signature,
+        )
+    except BaseException:
+        # Once consumed, a local/network exception has an ambiguous outcome.
+        status = (
+            "outcome_unknown"
+            if prepared.consumed
+            else "rejected_before_submission"
+        )
+        await attempts.set_status(order_hash, status)
+        raise
+    else:
+        if result.order_id and result.order_id.lower() != order_hash.lower():
+            await attempts.set_status(order_hash, "identity_mismatch")
+            raise RuntimeError("CLOB returned an unexpected order ID")
+        await attempts.record_response(order_hash, result)
+        return {
+            "success": result.success,
+            "orderId": result.order_id or order_hash,
+            "error": result.error,
+        }
 ```
 
-`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed. If submission has an ambiguous network result, reconcile its status instead of preparing an automatic duplicate.
+`prepared.order_hash` is the lowercase `0x`-prefixed EIP-712 digest of the canonical standard exchange `Order`. For EOA and Safe orders it also matches the browser-signing digest. POLY_1271 browsers sign an outer `TypedDataSign` wrapper, whose digest is intentionally different; `order_hash` always identifies the inner order that the CLOB and fills report. The property is computed on demand, is unchanged by trusted-state export/import, and is not added to the serialized schema.
+
+`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed.
+
+Treat any exception after `prepared.consumed` becomes true—including an HTTP timeout, disconnect, cancellation, or local failure around the network call—as `outcome_unknown`. Never submit that hash again and never automatically prepare a replacement. Reconcile by exact hash against both `await trader.get_open_orders(asset_id=token_id)` (`OpenOrder.id`) and your durable authenticated V2 fill source (`fill.order_hash`):
+
+```python
+async def reconcile_unknown(trader, attempt, fills):
+    open_orders = await trader.get_open_orders(asset_id=attempt.token_id)
+    open_order = next(
+        (order for order in open_orders if order.id.lower() == attempt.order_hash.lower()),
+        None,
+    )
+    matching_fills = await fills.by_order_hash(attempt.order_hash)
+    return {"openOrder": open_order, "fills": matching_fills}
+```
+
+An open order may already be partially filled (`size_matched` is nonzero), while a fully filled or canceled order will not remain open. Group all partial fills for the exact hash. Finding neither an open order nor a fill is not proof that submission failed: keep the attempt unknown and retry reconciliation with bounded backoff. The application-owned attempt store and fill source must be durable, wallet-scoped, and idempotent by `order_hash`; do not infer identity from token, side, amounts, timestamps, balances, or request ID.
+
+If a request-scoped trader was populated from a browser bundle or decrypted vault record, clear its credentials even when validation, signing, submission, or reconciliation fails:
+
+```python
+trader = await trader_from_browser_bundle(request_json)
+try:
+    result = await submit_order(trader, browser_result, prepared_orders, attempts)
+finally:
+    trader.close()
+```
 
 For a single-process application, a backend-only in-memory dictionary is sufficient. For multiple workers, serialize only with the SDK's trusted server-state methods and use a server-side store that can atomically take/delete by `requestId`:
 

{polynode-0.14.0 → polynode-0.14.1}/README.md

@@ -2,7 +2,9 @@
 
 Python SDK for the [Polynode](https://polynode.dev) real-time prediction market data platform.
 
-**New in v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
+**New in v0.14.1:** Every prepared user-owned order exposes its canonical V2 exchange `order_hash` before submission. This is the exact CLOB/open-order ID and fill `order_hash`; deposit-wallet orders hash the standard inner `Order`, not the POLY_1271 wallet-signing wrapper. Record it before the network attempt so timeouts can be reconciled without risking a duplicate.
+
+**In v0.14.0:** Web platforms can take a user from wallet authorization through an exact browser-signed user-owned order without exposing backend credentials. The SDK imports the shared versioned browser bundle into memory, produces a credential-free signing request with a complete order preview, supports one-time multi-worker state, validates canonical signatures and wallet identity, checks BUY collateral before prompting, and submits with exact zero builder attribution.
 
 **In v0.13.0:** Trading added explicit `user_owned` execution. Existing builder mode remains the default; opted-in wallets use zero builder attribution, one wallet-ownership authorization, and strict wallet-bound gasless credentials. Builder credentials and nonzero builder codes fail closed in this mode. EOA-controlled Safe and deposit wallets are supported; legacy Magic/proxy wallets are intentionally excluded from the first release.
 
@@ -502,29 +504,82 @@ const result = await fetch("/api/orders/submit", {
 }).then((response) => response.json());
 ```
 
-On the backend, atomically take the prepared object from session state, then validate and submit it:
+On the backend, atomically take the prepared object from session state, durably record the deterministic order identity, then validate and submit it:
 
 ```python
-async def submit_order(trader, browser_result, prepared_orders):
+async def submit_order(trader, browser_result, prepared_orders, attempts):
     # `take_once` must delete atomically so two workers cannot submit the same request.
     prepared = await prepared_orders.take_once(browser_result.request_id)
     if prepared is None:
         raise ValueError("Unknown or already-used signing request")
 
-    result = await trader.submit_prepared_user_owned_order(
-        prepared,
+    order_hash = prepared.order_hash
+    # This durable, idempotent write must commit before submission starts.
+    await attempts.create_once(
+        order_hash=order_hash,
         request_id=browser_result.request_id,
-        address=browser_result.address,
-        signature=browser_result.signature,
+        wallet=prepared.signing_request.address,
+        token_id=prepared.signing_request.order["tokenId"],
+        side=prepared.signing_request.order["side"],
+        status="submitting",
     )
-    return {
-        "success": result.success,
-        "orderId": result.order_id,
-        "error": result.error,
-    }
+
+    try:
+        result = await trader.submit_prepared_user_owned_order(
+            prepared,
+            request_id=browser_result.request_id,
+            address=browser_result.address,
+            signature=browser_result.signature,
+        )
+    except BaseException:
+        # Once consumed, a local/network exception has an ambiguous outcome.
+        status = (
+            "outcome_unknown"
+            if prepared.consumed
+            else "rejected_before_submission"
+        )
+        await attempts.set_status(order_hash, status)
+        raise
+    else:
+        if result.order_id and result.order_id.lower() != order_hash.lower():
+            await attempts.set_status(order_hash, "identity_mismatch")
+            raise RuntimeError("CLOB returned an unexpected order ID")
+        await attempts.record_response(order_hash, result)
+        return {
+            "success": result.success,
+            "orderId": result.order_id or order_hash,
+            "error": result.error,
+        }
 ```
 
-`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed. If submission has an ambiguous network result, reconcile its status instead of preparing an automatic duplicate.
+`prepared.order_hash` is the lowercase `0x`-prefixed EIP-712 digest of the canonical standard exchange `Order`. For EOA and Safe orders it also matches the browser-signing digest. POLY_1271 browsers sign an outer `TypedDataSign` wrapper, whose digest is intentionally different; `order_hash` always identifies the inner order that the CLOB and fills report. The property is computed on demand, is unchanged by trusted-state export/import, and is not added to the serialized schema.
+
+`prepare_user_owned_order()` supports V2 user-owned execution only, expires after five minutes by default, forces zero builder attribution, rejects positive fee authentication, and performs no submission. GTC, FOK, and FAK orders must omit expiration (zero is accepted and canonicalized to no expiration); GTD requires a fresh Unix-seconds expiration with the 60-second safety buffer, and the signing request is clamped to that window. `submit_prepared_user_owned_order()` verifies the request ID, expiry, connected wallet, stored wallet/funder identity, exact typed data, and recovered signer before consuming the request. A consumed request cannot be replayed.
+
+Treat any exception after `prepared.consumed` becomes true—including an HTTP timeout, disconnect, cancellation, or local failure around the network call—as `outcome_unknown`. Never submit that hash again and never automatically prepare a replacement. Reconcile by exact hash against both `await trader.get_open_orders(asset_id=token_id)` (`OpenOrder.id`) and your durable authenticated V2 fill source (`fill.order_hash`):
+
+```python
+async def reconcile_unknown(trader, attempt, fills):
+    open_orders = await trader.get_open_orders(asset_id=attempt.token_id)
+    open_order = next(
+        (order for order in open_orders if order.id.lower() == attempt.order_hash.lower()),
+        None,
+    )
+    matching_fills = await fills.by_order_hash(attempt.order_hash)
+    return {"openOrder": open_order, "fills": matching_fills}
+```
+
+An open order may already be partially filled (`size_matched` is nonzero), while a fully filled or canceled order will not remain open. Group all partial fills for the exact hash. Finding neither an open order nor a fill is not proof that submission failed: keep the attempt unknown and retry reconciliation with bounded backoff. The application-owned attempt store and fill source must be durable, wallet-scoped, and idempotent by `order_hash`; do not infer identity from token, side, amounts, timestamps, balances, or request ID.
+
+If a request-scoped trader was populated from a browser bundle or decrypted vault record, clear its credentials even when validation, signing, submission, or reconciliation fails:
+
+```python
+trader = await trader_from_browser_bundle(request_json)
+try:
+    result = await submit_order(trader, browser_result, prepared_orders, attempts)
+finally:
+    trader.close()
+```
 
 For a single-process application, a backend-only in-memory dictionary is sufficient. For multiple workers, serialize only with the SDK's trusted server-state methods and use a server-side store that can atomically take/delete by `requestId`:
 

polynode-0.14.1/polynode/_version.py

@@ -0,0 +1 @@
+__version__ = "0.14.1"

{polynode-0.14.0 → polynode-0.14.1}/polynode/trading/eip712.py

@@ -477,6 +477,18 @@ def validate_order_payload_pair_v2(
     funder_address: str,
 ) -> None:
     """Fail if prepared V2 order and wallet-signing payloads diverge."""
+    _validate_standard_order_payload_v2(order_payload)
+    expected_signing_payload = signing_payload_for_order_v2(
+        order_payload,
+        signature_type=signature_type,
+        funder_address=funder_address,
+    )
+    if signing_payload.to_dict() != expected_signing_payload.to_dict():
+        raise ValueError("prepared user-owned order and signing payload do not match")
+
+
+def _validate_standard_order_payload_v2(order_payload: Eip712Payload) -> None:
+    """Fail unless a payload is an exact standard V2 exchange Order."""
     if order_payload.primary_type != "Order":
         raise ValueError("prepared user-owned order has an invalid primary type")
     if order_payload.types != ORDER_TYPES_V2:
@@ -486,13 +498,23 @@ def validate_order_payload_pair_v2(
     expected_fields = {field["name"] for field in ORDER_TYPES_V2["Order"]}
     if set(order_payload.message) != expected_fields:
         raise ValueError("prepared user-owned order has invalid EIP-712 fields")
-    expected_signing_payload = signing_payload_for_order_v2(
-        order_payload,
-        signature_type=signature_type,
-        funder_address=funder_address,
-    )
-    if signing_payload.to_dict() != expected_signing_payload.to_dict():
-        raise ValueError("prepared user-owned order and signing payload do not match")
+
+
+def _standard_order_hash_v2(order_payload: Eip712Payload) -> str:
+    """Return the canonical exchange digest for one standard V2 Order."""
+    _validate_standard_order_payload_v2(order_payload)
+    try:
+        from eth_account.messages import encode_typed_data
+        from eth_utils import keccak
+    except ImportError:
+        raise ImportError(
+            "eth-account is required for trading. Install with: "
+            "pip install polynode[trading]"
+        )
+
+    signable = encode_typed_data(full_message=order_payload.to_dict())
+    digest = keccak(b"\x19\x01" + signable.header + signable.body)
+    return f"0x{digest.hex()}"
 
 
 def validate_canonical_user_owned_order_v2(

{polynode-0.14.0 → polynode-0.14.1}/polynode/trading/types.py

@@ -157,14 +157,15 @@ class Eip712Payload:
             "verifyingContract": "address",
             "salt": "bytes32",
         }
-        try:
-            domain_type = [
-                {"name": name, "type": domain_field_types[name]} for name in self.domain
-            ]
-        except KeyError as exc:
-            raise ValueError(
-                f"unsupported EIP-712 domain field: {exc.args[0]}"
-            ) from exc
+        unsupported_fields = set(self.domain) - set(domain_field_types)
+        if unsupported_fields:
+            unsupported_field = sorted(unsupported_fields)[0]
+            raise ValueError(f"unsupported EIP-712 domain field: {unsupported_field}")
+        domain_type = [
+            {"name": name, "type": type_name}
+            for name, type_name in domain_field_types.items()
+            if name in self.domain
+        ]
         return deepcopy(
             {
                 "domain": self.domain,
@@ -515,6 +516,63 @@ class PreparedUserOwnedOrder:
         """Whether this prepared order was discarded or used for submission."""
         return self._consumed
 
+    @property
+    def order_hash(self) -> str:
+        """Return the canonical V2 exchange Order EIP-712 digest.
+
+        This is the CLOB/open-order ID and fill ``order_hash``. For POLY_1271,
+        it hashes the inner standard Order, never the wallet-signing
+        ``TypedDataSign`` wrapper.
+        """
+        from .eip712 import (
+            _standard_order_hash_v2,
+            canonical_order_values_v2,
+            user_owned_order_preview_v2,
+            validate_canonical_user_owned_order_v2,
+        )
+
+        canonical_price, canonical_size = canonical_order_values_v2(
+            self._price,
+            self._size,
+            self._tick_size,
+        )
+        if self._price != canonical_price or self._size != canonical_size:
+            raise ValueError("prepared user-owned order price or size is not canonical")
+        validate_canonical_user_owned_order_v2(
+            self._order_payload,
+            self._signing_payload,
+            wallet_address=self._wallet_address,
+            funder_address=self._funder_address,
+            signature_type=self._signature_type,
+            token_id=self._token_id,
+            price=self._price,
+            size=self._size,
+            side=self._side,
+            tick_size=self._tick_size,
+            neg_risk=self._neg_risk,
+        )
+        if (
+            self.signing_request.version != "1"
+            or not isinstance(self.signing_request.address, str)
+            or self.signing_request.address.lower() != self._wallet_address.lower()
+        ):
+            raise ValueError("prepared user-owned order wallet binding is invalid")
+        if self.signing_request.typed_data != self._signing_payload.to_dict():
+            raise ValueError("prepared user-owned order signing request was modified")
+        expected_preview = user_owned_order_preview_v2(
+            self._order_payload,
+            token_id=self._token_id,
+            side=self._side,
+            price=self._price,
+            size=self._size,
+            order_type=self._order_type,
+            post_only=self._post_only,
+            expiration=self._expiration,
+        )
+        if self.signing_request.order != expected_preview:
+            raise ValueError("prepared user-owned order preview was modified")
+        return _standard_order_hash_v2(self._order_payload)
+
     def _unsigned_server_dict(self) -> dict[str, Any]:
         return {
             "version": "1",

{polynode-0.14.0 → polynode-0.14.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "polynode"
-version = "0.14.0"
+version = "0.14.1"
 description = "Python SDK for the Polynode real-time prediction market data platform"
 readme = "README.md"
 requires-python = ">=3.10"

polynode-0.14.0/polynode/_version.py

@@ -1 +0,0 @@
-__version__ = "0.14.0"