polynode 0.13.0__tar.gz → 0.14.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: polynode
-Version: 0.13.0
+Version: 0.14.0
 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.13.0:** Trading adds 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.
+**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.
+
+**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.
 
 **In v0.12.2:** Python provides the same core capabilities as the TypeScript and Rust SDKs: complete V3 API access, the V3 perps WebSocket, reconnect-aware settlement delivery, and PN1 orderbook integrity. Unknown additive events remain available as raw payloads, decimal values remain precision-safe, and any local queue eviction is reported.
 
@@ -293,7 +295,7 @@ async def main():
 asyncio.run(main())
 ```
 
-For the V2 order flow — required approvals, EIP-712 struct, fee math, and common failure modes — see `polynode/trading/V2_ORDER_FLOW.md` in the installed package.
+For the V2 order flow, required approvals, and common failure modes, see [docs.polynode.dev](https://docs.polynode.dev).
 
 V2 fees are determined at match time and are not signed into an order, so V2 payloads omit `feeRateBps`, `nonce`, and `taker`. Explicit legacy V1 mode still signs `feeRateBps`; for that path the SDK fetches `/fee-rate` and fails closed if fee, tick-size, or neg-risk metadata is unavailable or malformed.
 
@@ -313,7 +315,7 @@ from polynode.trading import (
 trader = PolyNodeTrader(TraderConfig(
     polynode_key=os.environ["POLYNODE_API_KEY"],
     execution_mode=ExecutionMode.USER_OWNED,
-    # Optional, explicit regional egress; direct is the default.
+    # Optional transport selection; direct is the default.
     # user_owned_clob_transport=UserOwnedClobTransport.PROXY,
 ))
 ready = await trader.ensure_ready(user_wallet_signer)
@@ -322,11 +324,268 @@ print(ready.execution_mode, ready.user_relayer_authorized)
 
 `user_wallet_signer` is a caller-controlled `RouterSigner`; the SDK asks it to sign scoped messages and never persists or transmits its private key. A private-key string is also accepted when the caller already manages it inside a trusted process. User-owned mode rejects builder credentials, nonzero builder codes, and credentials owned by another wallet. It supports EOA signers and EOA-controlled Safe or deposit wallets; legacy `POLY_PROXY` and Magic/DID signers are not supported in the first release. Normal CLOB authentication and Polymarket rate limits still apply.
 
-Signed CLOB requests go directly to Polymarket by default. Platforms that need Polynode's regional egress can explicitly set `user_owned_clob_transport=UserOwnedClobTransport.PROXY`; this transport never activates automatically and never falls back between paths. Fee-authenticated orders are not available in user-owned mode, and any positive effective `fee_bps` is rejected before an order is signed or submitted.
+`UserOwnedClobTransport.DIRECT` is the default. Integrations configured for `UserOwnedClobTransport.PROXY` must select it explicitly; the SDK never changes transport or falls back between paths automatically. Fee-authenticated orders are not available in user-owned mode, and any positive effective `fee_bps` is rejected before an order is signed or submitted.
+
+For browser-wallet integrations, begin authorization on the trusted backend with the trader's configured Polynode key. Keep the complete challenge in one-time backend state and return only its public fields:
+
+```python
+async def begin_wallet_authorization(trader, session, pending_authorizations):
+    challenge = await trader.begin_user_relayer_authorization(
+        session.wallet_address
+    )
+    await pending_authorizations.put_once(
+        challenge.challenge_id,
+        challenge,
+        expires_at=challenge.expires_at,
+    )
+    return {
+        "challengeId": challenge.challenge_id,
+        "address": challenge.address,
+        "expiresAt": challenge.expires_at,
+        "signatureType": challenge.signature_type,
+        "message": challenge.message,
+    }
+```
+
+The connected wallet signs the exact message without reconstructing it:
+
+```javascript
+const [address] = await window.ethereum.request({
+  method: "eth_requestAccounts",
+});
+if (address.toLowerCase() !== challenge.address.toLowerCase()) {
+  throw new Error("Connected wallet changed");
+}
+const signature = await window.ethereum.request({
+  method: "personal_sign",
+  params: [challenge.message, address],
+});
+```
+
+Atomically take the original challenge and complete it against the wallet bound to the authenticated application session:
+
+```python
+async def complete_wallet_authorization(
+    trader, session, browser_result, pending_authorizations
+):
+    challenge = await pending_authorizations.take_once(
+        browser_result.challenge_id
+    )
+    if challenge is None:
+        raise ValueError("Unknown or already-used authorization challenge")
+    credentials = await trader.complete_user_relayer_authorization(
+        challenge,
+        browser_result.signature,
+        session.wallet_address,
+    )
+    return credentials
+```
+
+Completion validates the challenge, signature shape, expected wallet, and returned credential owner, then keeps the credential only in that trader instance's memory. It does not write the signature or credential to SQLite or another store. If the account must survive the process, encrypt the returned credential in your own wallet-bound secret manager. The global `begin_user_relayer_authorization()` and `complete_user_relayer_authorization()` helpers remain available when explicit service configuration is preferable.
+
+For long-running services, `await trader.authorize_user_owned_execution(signer)` provides the combined convenience flow. Backend secret-manager storage is recommended, and the wallet-owned credential can be supplied later as `TraderConfig.user_relayer_credentials`. Never log it, commit it, or persist it in cookies, local storage, IndexedDB, or other browser storage. Current-tab memory is the explicitly supported, higher-risk session-only option described below.
+
+##### Browser wallet to submitted order
+
+Use the split-phase order API when a browser wallet signs but your backend owns submission. The backend retains the Polynode key, wallet-owned relayer credential, and CLOB credentials. The browser receives only one short-lived EIP-712 request and returns its signature.
+
+Create a separate user-owned trader for each active wallet context. This example uses an in-memory SDK database so decrypted credentials exist only for the process lifetime; load them from your own encrypted secret store:
+
+```python
+from polynode.trading import (
+    ExecutionMode,
+    PolyNodeTrader,
+    SignatureType,
+    TraderConfig,
+    UserRelayerCredentials,
+)
+
+trader = PolyNodeTrader(TraderConfig(
+    polynode_key=server_secrets.polynode_key,
+    db_path=":memory:",
+    execution_mode=ExecutionMode.USER_OWNED,
+    user_relayer_credentials=UserRelayerCredentials(
+        key=wallet_secrets.relayer_key,
+        address=wallet_address,
+    ),
+))
+trader.link_credentials(
+    wallet=wallet_address,
+    funder_address=funder_address,
+    signature_type=SignatureType.EOA,  # This minimal example uses an EOA account.
+    api_key=wallet_secrets.clob_key,
+    api_secret=wallet_secrets.clob_secret,
+    api_passphrase=wallet_secrets.clob_passphrase,
+)
+```
+
+There are two safe credential patterns:
+
+- **Backend vault (recommended for durable accounts):** store each wallet's relayer and CLOB credentials encrypted under that wallet identity, decrypt them only into the user-owned trader, and close the trader after use.
+- **Session-only browser handoff (higher risk):** if your frontend SDK holds a versioned user-owned bundle only in current-tab memory, send that complete bundle once to an authenticated backend endpoint over HTTPS and import it into an in-memory trader:
+
+```json
+{
+  "version": "1",
+  "executionMode": "user_owned",
+  "wallet": {
+    "address": "0x...",
+    "funderAddress": "0x...",
+    "signatureType": 0
+  },
+  "clobCredentials": {
+    "apiKey": "...",
+    "apiSecret": "...",
+    "apiPassphrase": "..."
+  },
+  "userRelayerCredentials": {
+    "key": "...",
+    "address": "0x..."
+  }
+}
+```
+
+`signatureType` is `0` for an EOA, `2` for an EOA-controlled Safe, or `3` for an EOA-controlled deposit wallet.
+
+```python
+async def trader_from_browser_bundle(request_json):
+    trader = PolyNodeTrader(TraderConfig(
+        polynode_key=server_secrets.polynode_key,
+        db_path=":memory:",
+        execution_mode=ExecutionMode.USER_OWNED,
+    ))
+    await trader.import_user_owned_browser_bundle(request_json)
+    return trader
+```
+
+`import_user_owned_browser_bundle()` accepts only the exact version-1 `user_owned` schema, validates the relayer owner plus wallet/funder/signature-type binding, redacts the model representation, and refuses any database other than `:memory:`. The CLOB API secret may use canonical standard Base64 or Base64url, padded or unpadded; malformed padding, whitespace, empty values, and noncanonical encodings are rejected before the trader is mutated. Treat the request body as a secret: exclude it from access logs, traces, error reports, analytics, and replay queues. Do not retain it after the session.
+
+When your application receives a validated order intent, prepare it without submitting:
+
+```python
+from polynode.trading import OrderParams
+
+async def prepare_order(trader, order_intent, prepared_orders):
+    prepared = await trader.prepare_user_owned_order(OrderParams(
+        token_id=order_intent.token_id,
+        side="BUY",
+        price=0.52,
+        size=10,
+        type="GTC",
+    ))
+
+    # Save the complete object in an application-owned, backend-only one-time store.
+    await prepared_orders.put_once(
+        prepared.signing_request.request_id,
+        prepared,
+        expires_at=prepared.signing_request.expires_at,
+    )
+
+    # This is the only value returned to the browser.
+    return prepared.signing_request.to_dict()
+```
+
+The browser request has one language-neutral shape: `version`, `requestId`, `address`, Unix-seconds `expiresAt`, `typedData`, and `order`. The credential-free `order` preview includes the canonical positive token ID, side, tick-rounded price, two-decimal round-down size, order type, post-only and expiration controls, maker, signer, `makerAmount`, and `takerAmount`. Those are the exact values used for signing; show them to the user, but never accept a browser-edited copy as submission state.
+
+For a BUY, preparation reads the returned preview's `maker` (the active funder) and requires its PolyUSD balance to cover the exact canonical `makerAmount` before returning anything for wallet signature. This check never moves or wraps funds. `ensure_ready()` deploys/configures the wallet but does not create collateral, so your platform must fund or wrap into that funder first and prepare a new order after any balance change.
+
+Require an authenticated application session for both endpoints, bind that session to the expected wallet on the backend, validate that the user may place the requested order, and apply normal CSRF protection when using cookies. A wallet address supplied by the browser is not application authentication.
+
+Verify the connected address and sign the exact `typedData` object in the browser. Do not rebuild or edit it:
+
+```javascript
+const signingRequest = await fetch("/api/orders/prepare", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify(orderIntent),
+}).then((response) => response.json());
+
+const [connectedAddress] = await window.ethereum.request({
+  method: "eth_requestAccounts",
+});
+const chainId = await window.ethereum.request({ method: "eth_chainId" });
+if (
+  signingRequest.version !== "1"
+  || !Number.isSafeInteger(signingRequest.expiresAt)
+  || Math.floor(Date.now() / 1000) >= signingRequest.expiresAt
+) {
+  throw new Error("Order signing request is invalid or expired");
+}
+if (chainId.toLowerCase() !== "0x89") {
+  throw new Error("Switch the wallet to Polygon");
+}
+if (connectedAddress.toLowerCase() !== signingRequest.address.toLowerCase()) {
+  throw new Error("Connect the wallet that owns this trading account");
+}
+
+// Display signingRequest.order for confirmation before requesting the signature.
+
+const signature = await window.ethereum.request({
+  method: "eth_signTypedData_v4",
+  params: [connectedAddress, JSON.stringify(signingRequest.typedData)],
+});
+
+const result = await fetch("/api/orders/submit", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({
+    requestId: signingRequest.requestId,
+    address: connectedAddress,
+    signature,
+  }),
+}).then((response) => response.json());
+```
+
+On the backend, atomically take the prepared object from session state, then validate and submit it:
+
+```python
+async def submit_order(trader, browser_result, prepared_orders):
+    # `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,
+        request_id=browser_result.request_id,
+        address=browser_result.address,
+        signature=browser_result.signature,
+    )
+    return {
+        "success": result.success,
+        "orderId": result.order_id,
+        "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.
+
+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`:
+
+```python
+import json
+import time
+
+# Prepare worker: expire server state with the signing request.
+ttl_seconds = prepared.signing_request.expires_at - int(time.time())
+if ttl_seconds <= 0:
+    raise ValueError("Signing request already expired")
+await server_store.put(
+    prepared.signing_request.request_id,
+    json.dumps(trader.export_prepared_user_owned_order(prepared)),
+    ttl_seconds=ttl_seconds,
+)
+
+# Submit worker: `take_once` must atomically return and delete the value.
+raw_state = await server_store.take_once(browser_result.request_id)
+if raw_state is None:
+    raise ValueError("Unknown or already-used signing request")
+prepared = trader.import_prepared_user_owned_order(json.loads(raw_state))
+```
 
-For browser-wallet integrations, the typed `begin_user_relayer_authorization()` and `complete_user_relayer_authorization()` functions let a trusted backend request a validated message, send only that message to the user's browser for signing, and complete authorization for the same expected address. Keep the Polynode API key on the backend. Neither primitive writes the wallet signature or returned credential to local storage.
+The trader authenticates exported state with a domain-separated HMAC derived from its configured backend Polynode key, verifies it on import and again before submission, then strictly reconstructs the exact V2 order from the retained market inputs. Every worker that prepares, restores, or submits these requests must use the same key. The serialized tag never contains that key, and rotating the key intentionally invalidates outstanding prepared requests. Accept exported state only from your own authenticated server-side store; never accept it from a browser. The object contains no credentials, but it contains submission controls and must remain one-time.
 
-For long-running services, `await trader.authorize_user_owned_execution(signer)` provides the combined convenience flow. Its wallet-owned credential can be kept in a server-side secret manager and supplied later as `TraderConfig.user_relayer_credentials`. Never log it, commit it, or store it in a browser.
+Never serialize the complete prepared object to the browser; only serialize `prepared.signing_request.to_dict()`. Never place the Polynode key, wallet-owned relayer credential, CLOB credentials, or authenticated submission headers in frontend code, cookies, browser storage, analytics, or logs.
 
 `ensure_ready()` is the one-call onboarding path for user-owned Safe and deposit-wallet accounts: it deploys the selected wallet when needed, applies the base trading approvals, verifies both results, and only then reports the account ready. New deposit-wallet integrations must resolve the current address asynchronously: