polymach 0.1.0__tar.gz

polymach-0.1.0/DOCUMENTATION.md

@@ -0,0 +1,875 @@
+# PolyMach Documentation
+
+This file is the single-file operational reference for the public `polymach` SDK.
+
+It is written for agentic ingestion:
+
+- it focuses on the actual public API surface
+- it describes the startup and payment state machine
+- it includes concrete examples
+- it distinguishes payment-wallet concerns from trading-wallet concerns
+
+## Purpose
+
+`polymach` is the public Python SDK for the private PolyMach execution engine on Polymarket.
+
+What happens at runtime:
+
+1. the Python package is installed with `uv add polymach`
+2. on first use, the SDK resolves or downloads the correct signed runtime binary
+3. the SDK verifies the signed release manifest and artifact hash
+4. the runtime is launched locally
+5. the SDK checks for a machine-bound license
+6. if needed, the SDK returns payment instructions or submits the payment directly
+7. after license activation, the runtime is used for low-latency discovery, quotes, streaming, and trading
+
+Important payment model:
+
+- the SDK returns the exact payment instructions for the current machine when payment is needed
+- the user or agent supplies the payer wallet or signer if payment is automated
+
+The SDK is public. The Rust engine source is not in this repo.
+
+## Install
+
+```bash
+uv add polymach
+```
+
+Default runtime bootstrap URL:
+
+```text
+https://github.com/polymach-dev/build/releases/latest/download/index.json
+```
+
+In the normal case, users do not need a local Rust toolchain or a local checkout of the private engine repo.
+
+## Supported Machines And Builds
+
+The SDK bootstrap selects a runtime artifact from the signed release catalog based on:
+
+- host platform
+- host architecture
+- Linux libc family
+- x86_64 CPU level
+
+PolyMach ships native runtime builds for each supported target class. The release process produces target-specific artifacts instead of relying on one generic cross-platform binary.
+
+Current release targets:
+
+- Linux `x86_64` glibc `v2`
+  Artifact id: `x86_64-unknown-linux-gnu-v2`
+- Linux `x86_64` glibc `v3`
+  Artifact id: `x86_64-unknown-linux-gnu-v3`
+- Linux `x86_64` glibc `v4`
+  Artifact id: `x86_64-unknown-linux-gnu-v4`
+- Linux `aarch64` glibc generic ARM64
+  Artifact id: `aarch64-unknown-linux-gnu`
+- macOS `aarch64` native Apple Silicon
+  Artifact id: `aarch64-apple-darwin`
+
+Why there are multiple Linux `x86_64` artifacts:
+
+- `v2` is the broad baseline build
+- `v3` is compiled for AVX2-class machines
+- `v4` is compiled for AVX-512-capable machines
+- the SDK chooses the fastest compatible build for the current host instead of forcing every machine onto the same binary
+
+Selection behavior:
+
+- `v4` hosts prefer `v4`
+- `v3` hosts prefer `v3`
+- `v2` hosts use `v2`
+- the SDK will not select an artifact that requires a higher CPU level than the current machine
+- Linux `aarch64` hosts use `aarch64-unknown-linux-gnu`
+- macOS Apple Silicon hosts use `aarch64-apple-darwin`
+
+Operationally, that means the public release channel is intended to contain individually built native artifacts for:
+
+- modern Linux x86_64 fleets at multiple CPU tiers
+- Linux ARM64 systems such as Graviton
+- Apple Silicon macOS systems
+
+If you need to pin a specific published build instead of letting the SDK choose automatically, set:
+
+- `POLYMACH_ARTIFACT_ID`
+
+Example:
+
+```bash
+export POLYMACH_ARTIFACT_ID=x86_64-unknown-linux-gnu-v2
+```
+
+If you run on a target outside the published release set, provide a compatible local runtime binary with `POLYMACH_BIN`.
+
+## Primary Entry Point
+
+The main entry point is `PolyMach`.
+
+```python
+from polymach import PolyMach
+
+engine = PolyMach()
+```
+
+Constructor options:
+
+- `binary`: optional explicit path to a local `polymach` runtime binary
+- `license_path`: optional explicit path to the local machine license file
+- `env`: optional mapping of environment variables used by the runtime and SDK
+- `persistent`: optional override for persistent-session behavior
+
+The instance exposes these domain clients:
+
+- `engine.system`
+- `engine.session`
+- `engine.license`
+- `engine.account`
+- `engine.discover`
+- `engine.market`
+- `engine.orders`
+- `engine.trades`
+
+It also exposes convenience wrappers around the most important flows.
+
+## Public State Machine
+
+The important startup states are:
+
+1. runtime missing
+2. runtime available but no valid local license
+3. payment required
+4. payment submitted and waiting for confirmation
+5. license activated
+6. runtime ready for trading
+
+The SDK presents that state machine through `start()`, `ensure_ready()`, `pay()`, and `pay_and_start()`.
+
+### `start()`
+
+`start()` is the recommended first-run flow.
+
+Behavior:
+
+- if a valid local license already exists, it returns `StartResult(ready=True, ...)`
+- if no valid license exists and no `tx_hash` is provided, it returns `StartResult(ready=False, payment=...)`
+- if `tx_hash` is provided, it activates the machine license and returns `StartResult(ready=True, activation=...)`
+
+### `ensure_ready()`
+
+`ensure_ready()` is the same as `start()`, except it raises `PaymentRequiredError` instead of returning `ready=False`.
+
+Use it when your agent wants exception-driven control flow.
+
+### `pay()`
+
+`pay()` fetches a machine-specific payment request and submits the on-chain Polygon payment.
+
+It returns `SubmittedPayment`.
+
+### `pay_and_start()`
+
+`pay_and_start()` is the one-shot path.
+
+Behavior:
+
+- if a valid license already exists, it starts normally
+- if `tx_hash` is provided, it resumes activation without submitting a new payment
+- otherwise it submits the payment, activates the license, and optionally prewarms the runtime
+
+This is the shortest path for fully automated agents.
+
+## Core Startup Flows
+
+## Flow 1: Manual Payment Then Activate
+
+This is the safest and most explicit first-run path.
+
+```python
+from polymach import PolyMach
+
+engine = PolyMach()
+
+start = engine.start()
+if not start.ready:
+    payment = start.payment
+    print(payment.amount_display)
+    print(payment.token_symbol)
+    print(payment.token_address)
+    print(payment.chain_id)
+    raise SystemExit("Send that exact Polygon payment, then call start(tx_hash=...)")
+
+start = engine.start(tx_hash="0xYOUR_PAYMENT_TX_HASH")
+print(start.ready)
+print(start.license_status.valid)
+print(start.activation.tx_hash if start.activation else None)
+```
+
+What to inspect when `ready=False`:
+
+- `start.payment.amount_display`
+- `start.payment.token_symbol`
+- `start.payment.token_address`
+- `start.payment.chain_id`
+- `start.payment.min_confirmations`
+
+Important:
+
+- the payment request is machine-specific
+- do not reuse a payment request from another machine
+- follow the exact payment instructions returned by the SDK
+
+## Flow 2: Exception-Driven Manual Payment
+
+```python
+from polymach import PaymentRequiredError, PolyMach
+
+engine = PolyMach()
+
+try:
+    engine.ensure_ready()
+except PaymentRequiredError as exc:
+    payment = exc.payment
+    print(exc.message)
+    print(payment.amount_display, payment.token_symbol)
+```
+
+This is useful when your orchestrator already handles retries and exceptions centrally.
+
+## Flow 3: Automated Payment
+
+`pay()` submits the Polygon payment directly.
+
+```python
+from polymach import LocalAccountSigner, PolyMach
+
+engine = PolyMach()
+signer = LocalAccountSigner.from_private_key("0xYOUR_PAYMENT_WALLET_PRIVATE_KEY")
+
+submitted = engine.pay(
+    signer=signer,
+    cycles=1,
+)
+
+print(submitted.tx_hash)
+print(submitted.sender_address)
+print(submitted.amount_display)
+print(submitted.confirmations)
+```
+
+The payment wallet must hold:
+
+- the required payment token on Polygon
+- a small amount of POL for gas
+
+## Flow 4: Automated Payment And Start
+
+```python
+from polymach import LocalAccountSigner, PaymentPendingError, PolyMach
+
+engine = PolyMach()
+signer = LocalAccountSigner.from_private_key("0xYOUR_PAYMENT_WALLET_PRIVATE_KEY")
+
+try:
+    start = engine.pay_and_start(
+        signer=signer,
+        prewarm_tokens=["TOKEN_ID"],
+    )
+except PaymentPendingError as exc:
+    start = engine.start(tx_hash=exc.tx_hash)
+
+print(start.ready)
+print(start.license_status.valid)
+```
+
+This is the preferred path for agents that are allowed to control the payment wallet directly.
+
+## Flow 5: Resume After A Broadcast But Slow Confirmation
+
+If the payment transaction is broadcast but confirmation polling times out, the SDK raises `PaymentPendingError`.
+
+Useful fields:
+
+- `exc.tx_hash`
+- `exc.confirmations`
+- `exc.required_confirmations`
+- `exc.attempted_tx_hashes`
+
+Recovery path:
+
+```python
+from polymach import LocalAccountSigner, PaymentPendingError, PolyMach
+
+engine = PolyMach()
+signer = LocalAccountSigner.from_private_key("0xYOUR_PAYMENT_WALLET_PRIVATE_KEY")
+
+try:
+    start = engine.pay_and_start(signer=signer)
+except PaymentPendingError as exc:
+    # wait, monitor, or persist the tx hash externally
+    start = engine.pay_and_start(tx_hash=exc.tx_hash)
+
+print(start.ready)
+```
+
+## Cold Start, Warm Start, And Bootstrap
+
+On `PolyMach()` creation, the runtime is not necessarily started yet.
+
+The first meaningful command will:
+
+- look for an explicitly configured binary
+- look for package, repo, or `PATH` binaries unless those paths are disabled
+- if no local binary is suitable, download the correct artifact from the signed release catalog
+- cache the runtime locally
+
+Relevant bootstrap environment variables:
+
+- `POLYMACH_RELEASE_INDEX_URL`
+- `POLYMACH_RELEASE_BASE_URL`
+- `POLYMACH_RELEASE_PUBLIC_KEY`
+- `POLYMACH_RELEASE_TOKEN`
+- `POLYMACH_ARTIFACT_ID`
+- `POLYMACH_BIN`
+- `POLYMACH_CACHE_DIR`
+
+Most users do not need to set any of these.
+
+## Prewarming And Session Management
+
+The runtime can prewarm token-specific state for lower latency.
+
+```python
+from polymach import PolyMach
+
+engine = PolyMach()
+engine.ensure_ready(tx_hash="0xYOUR_PAYMENT_TX_HASH")
+
+prewarm = engine.prewarm(
+    ["TOKEN_ID_1", "TOKEN_ID_2"],
+    quotes=True,
+    order_metadata=True,
+    last_trade=True,
+)
+
+print(prewarm)
+print(engine.session_status())
+```
+
+Why prewarm:
+
+- hot quote path
+- hot midpoint path
+- cached order metadata
+- lower latency before the first live order
+
+If your agent targets a small set of active markets, prewarm them before entering the main trading loop.
+
+## Market Data
+
+### Midpoint
+
+```python
+mid = engine.midpoint("TOKEN_ID")
+print(mid.token_id, mid.midpoint)
+```
+
+Returned type:
+
+- `MidpointResponse`
+
+Fields:
+
+- `token_id`
+- `midpoint`
+
+### Quote
+
+```python
+quote = engine.quote("TOKEN_ID")
+print(quote.midpoint, quote.bid, quote.ask)
+```
+
+Returned type:
+
+- `MarketQuote`
+
+Fields:
+
+- `midpoint`
+- `bid`
+- `ask`
+
+### Streaming Quotes
+
+```python
+for snapshot in engine.stream_quotes(
+    ["TOKEN_ID"],
+    interval_ms=100,
+    include_last_trade=True,
+    count=5,
+):
+    print(snapshot.timestamp)
+    for q in snapshot.quotes:
+        print(q.token_id, q.midpoint, q.bid, q.ask, q.last_trade)
+```
+
+Returned stream item type:
+
+- `QuoteStreamSnapshot`
+
+## Discovery
+
+### Search Markets
+
+```python
+markets = engine.discover_markets(
+    query="btc 5m",
+    limit=10,
+    with_live=True,
+)
+
+for market in markets:
+    print(market.slug, market.question)
+```
+
+### Get A Single Market
+
+```python
+market = engine.discover_market(slug="btc-updown-5m-...")
+print(market.slug)
+print(market.question)
+for outcome in market.outcomes:
+    print(outcome.outcome, outcome.token_id)
+```
+
+### Search Across Entities
+
+```python
+results = engine.search(
+    "btc",
+    limit=10,
+    include_profiles=False,
+    with_live=True,
+)
+
+print(len(results.markets), len(results.events))
+```
+
+Relevant return types:
+
+- `DiscoveryMarket`
+- `DiscoveryEvent`
+- `DiscoverySearchResults`
+
+Use `with_live=True` when you want live quote fields embedded into discovery results.
+
+## Account And Portfolio
+
+### Healthcheck
+
+```python
+health = engine.healthcheck(token_id="TOKEN_ID")
+print(health.collateral_balance_usdc)
+print(health.token_balance)
+print(health.midpoint)
+print(health.bid, health.ask)
+```
+
+This is the best compact account-state call when you want balances plus current market context.
+
+### Portfolio
+
+```python
+portfolio = engine.portfolio("TOKEN_ID")
+print(portfolio.token_id)
+print(portfolio.position_qty)
+print(portfolio.avg_entry_price)
+```
+
+## Orders
+
+Live order methods require the live-trading environment to be configured.
+
+### Limit Order
+
+```python
+receipt = engine.post_limit(
+    "buy",
+    "TOKEN_ID",
+    5.0,
+    0.01,
+    order_type="GTC",
+)
+
+print(receipt.order_id)
+print(receipt.qty, receipt.limit_price)
+```
+
+Returned type:
+
+- `LimitOrderReceipt`
+
+### Timed Limit Order
+
+```python
+timed = engine.post_limit(
+    "buy",
+    "TOKEN_ID",
+    5.0,
+    0.01,
+    order_type="GTC",
+    timed=True,
+)
+
+print(timed.receipt.order_id)
+print(timed.timing.total_seconds)
+print(timed.timing.http_seconds)
+```
+
+Returned type:
+
+- `TimedLimitResponse`
+
+Use `timed=True` when the agent wants latency breakdowns for submissions.
+
+### Market Buy
+
+```python
+fill = engine.market_buy("TOKEN_ID", 25.0)
+print(fill.order_id, fill.qty, fill.fill_price)
+```
+
+### Market Sell
+
+```python
+fill = engine.market_sell("TOKEN_ID", 5.0)
+print(fill.order_id, fill.qty, fill.fill_price)
+```
+
+### Inspect And Cancel Orders
+
+```python
+orders = engine.list_orders()
+for order in orders:
+    print(order.order_id, order.status, order.remaining_size)
+
+if orders:
+    result = engine.cancel_order(orders[0].order_id)
+    print(result.order_id, result.canceled)
+```
+
+Also available:
+
+- `engine.get_order(order_id)`
+- `engine.cancel_open_orders(token_id)`
+- `engine.cancel_all_open_orders()`
+
+## Trades
+
+```python
+page = engine.list_trades()
+for trade in page.trades:
+    print(trade.trade_id, trade.side, trade.price, trade.size)
+```
+
+You can also fetch a single trade:
+
+```python
+trade = engine.get_trade("TRADE_ID")
+print(trade)
+```
+
+## License And Machine Identity
+
+### Machine Fingerprint
+
+```python
+fingerprint = engine.fingerprint()
+print(fingerprint.fingerprint)
+```
+
+Use this if you need to reason explicitly about machine-bound licensing.
+
+### License Status
+
+```python
+status = engine.license_status()
+print(status.valid, status.message)
+```
+
+### Verify The Installed License
+
+```python
+claims = engine.verify_license()
+print(claims.license_id)
+print(claims.machine_fingerprint)
+print(claims.expires_at)
+```
+
+### Install An Existing License File
+
+```python
+installed_path = engine.install_license("/path/to/license.json")
+print(installed_path)
+```
+
+## Pricing And Payment Requests
+
+### Read Catalog Pricing
+
+```python
+catalog = engine.pricing()
+print(catalog.cycle_price_usdc)
+print(catalog.token_address)
+print(catalog.min_confirmations)
+```
+
+### Get The Exact Machine-Specific Payment Request
+
+```python
+payment = engine.payment_request(cycles=2)
+print(payment.machine_fingerprint)
+print(payment.amount_display)
+print(payment.amount_raw)
+```
+
+This is the object that should drive manual or automated payment execution.
+
+## Live Trading Environment
+
+The payment wallet and the trading wallet are different concerns.
+
+Venue availability is a separate concern from SDK install, runtime bootstrap,
+payment, and license activation. Those steps can succeed while Polymarket still
+refuses live trading from the current IP address, network, or jurisdiction.
+Before depending on live order flow, confirm venue access from the actual host
+that will run the strategy.
+
+### Payment Wallet
+
+Used by:
+
+- `pay()`
+- `pay_and_start()` when the SDK submits the payment
+
+Relevant inputs:
+
+- `signer=LocalAccountSigner.from_private_key(...)`
+- `private_key=...`
+- `POLYMACH_WALLET_PRIVATE_KEY` as a fallback
+
+### Trading Wallet
+
+Used by the runtime for actual Polymarket trading.
+
+Relevant environment variables:
+
+- `POLYMACH_LIVE_ENABLED=true`
+- `POLYMACH_LIVE_ACK=I_UNDERSTAND_REAL_MONEY_RISK`
+- `POLYMACH_POLYMARKET_PRIVATE_KEY=0x...`
+- `POLYMACH_POLYMARKET_SIGNATURE_TYPE=0`
+
+`POLYMACH_POLYMARKET_SIGNATURE_TYPE` values:
+
+- `0` = EOA
+- `1` = proxy
+- `2` = Gnosis Safe
+
+If the signer and funded trading address differ, also set:
+
+- `POLYMACH_POLYMARKET_FUNDER`
+
+If you use Polymarket API credentials, set all three:
+
+- `POLYMACH_POLYMARKET_API_KEY`
+- `POLYMACH_POLYMARKET_API_SECRET`
+- `POLYMACH_POLYMARKET_API_PASSPHRASE`
+
+Minimal live-trading shell setup:
+
+```bash
+export POLYMACH_LIVE_ENABLED=true
+export POLYMACH_LIVE_ACK=I_UNDERSTAND_REAL_MONEY_RISK
+export POLYMACH_POLYMARKET_PRIVATE_KEY=0xYOUR_TRADING_WALLET_PRIVATE_KEY
+export POLYMACH_POLYMARKET_SIGNATURE_TYPE=0
+```
+
+## Payment Configuration
+
+Relevant payment environment variables:
+
+- `POLYMACH_LICENSE_BASE_URL`
+- `POLYMACH_LICENSE_TOKEN`
+- `POLYMACH_POLYGON_RPC_URL`
+- `POLYMACH_POLYGON_RPC_URLS`
+- `POLYMACH_WALLET_PRIVATE_KEY`
+- `POLYMACH_PAYMENT_GAS_LIMIT`
+- `POLYMACH_PAYMENT_GAS_PRICE_WEI`
+- `POLYMACH_PAYMENT_REPLACEMENT_ATTEMPTS`
+- `POLYMACH_PAYMENT_REPLACEMENT_GAS_BUMP_PERCENT`
+
+Default Polygon RPC fallback order:
+
+```text
+https://polygon.publicnode.com
+https://1rpc.io/matic
+https://polygon-rpc.com
+```
+
+### Automated Payment With Replacement Controls
+
+```python
+from polymach import LocalAccountSigner, PolyMach
+
+engine = PolyMach()
+signer = LocalAccountSigner.from_private_key("0xYOUR_PAYMENT_WALLET_PRIVATE_KEY")
+
+submitted = engine.pay(
+    signer=signer,
+    replacement_attempts=2,
+    replacement_gas_bump_percent=25,
+    timeout_seconds=180.0,
+)
+
+print(submitted.tx_hash)
+```
+
+Use this if you want limited same-nonce replacement attempts for pending payment transactions.
+
+## Recommended Agent Recipes
+
+## Recipe 1: Minimal Install Then Manual Payment
+
+```python
+from polymach import PolyMach
+
+engine = PolyMach()
+result = engine.start()
+
+if result.ready:
+    print("ready")
+else:
+    print(result.payment.token_address)
+    print(result.payment.amount_display)
+```
+
+## Recipe 2: Automated Agent Startup
+
+```python
+from polymach import LocalAccountSigner, PaymentPendingError, PolyMach
+
+engine = PolyMach()
+payment_signer = LocalAccountSigner.from_private_key("0xPAYMENT_WALLET_KEY")
+
+try:
+    start = engine.pay_and_start(
+        signer=payment_signer,
+        prewarm_tokens=["TOKEN_ID"],
+        prewarm_last_trade=True,
+    )
+except PaymentPendingError as exc:
+    start = engine.start(tx_hash=exc.tx_hash)
+
+quote = engine.quote("TOKEN_ID")
+print(quote.midpoint)
+```
+
+## Recipe 3: Discover Then Trade
+
+```python
+from polymach import PolyMach
+
+engine = PolyMach()
+engine.ensure_ready(tx_hash="0xYOUR_PAYMENT_TX_HASH")
+
+market = engine.discover_market(slug="btc-updown-5m-...")
+token_id = market.outcomes[0].token_id
+
+engine.prewarm([token_id], last_trade=True)
+quote = engine.quote(token_id)
+
+if quote.ask is not None and quote.ask <= 0.10:
+    receipt = engine.post_limit("buy", token_id, 5.0, 0.10)
+    print(receipt.order_id)
+```
+
+## Recipe 4: Measure Order Submission Time
+
+```python
+timed = engine.post_limit(
+    "buy",
+    "TOKEN_ID",
+    5.0,
+    0.01,
+    timed=True,
+)
+
+print(timed.timing.total_seconds)
+print(timed.timing.http_seconds)
+print(timed.timing.build_sign_seconds)
+```
+
+## Common Errors
+
+### `PaymentRequiredError`
+
+Raised by:
+
+- `ensure_ready()`
+
+Meaning:
+
+- no valid local license exists yet
+- payment instructions are attached on `.payment`
+
+### `PaymentPendingError`
+
+Raised by:
+
+- `pay()`
+- `pay_and_start()`
+
+Meaning:
+
+- a payment transaction was broadcast or attempted
+- confirmation polling did not finish cleanly before timeout
+- the caller should inspect `.tx_hash` and possibly `.attempted_tx_hashes`
+
+### `BinaryNotFoundError`
+
+Meaning:
+
+- the SDK could not find a usable local runtime binary
+- and auto-download was disabled or failed before a valid binary was installed
+
+### `CommandError`
+
+Meaning:
+
+- the local runtime command failed
+
+Useful fields:
+
+- `.command`
+- `.exit_code`
+- `.stdout`
+- `.stderr`
+
+### `PolyMachError`
+
+Base runtime error class for SDK-level failures.
+
+## Security And Operational Notes
+
+- Prefer a dedicated low-balance payment wallet for automated subscription payments.
+- Keep payment-wallet and trading-wallet responsibilities separate unless you have a reason not to.
+- Keep private keys out of shell history, logs, prompts, and chat transcripts.
+- Prewarm active token ids before latency-sensitive trading.
+- Persist `PaymentPendingError.tx_hash` externally if your agent needs reliable restart recovery.
+- Use `timed=True` on limit orders when you want latency telemetry for benchmarking or control logic.
+
+## Legal
+
+- MIT license: [`LICENSE`](LICENSE)
+- legal disclaimer: [`LEGAL.md`](LEGAL.md)