tpluspy 0.2.1__tar.gz → 0.2.4__tar.gz

{tpluspy-0.2.1 → tpluspy-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpluspy
-Version: 0.2.1
+Version: 0.2.4
 Summary: tpluspy: Client utilities for interacting with tplus
 Home-page: https://github.com/tpluslabs/tpluspy
 Author: TPlus Labs
@@ -81,6 +81,28 @@ To install, use either `pip` or `uv pip`:
 uv pip install -e .
 ```
 
+## Onboarding with Codex CLI
+
+This repo includes a Codex-discoverable onboarding skill at
+`.agents/skills/onboard` for connecting an EVM wallet key to T+, checking whether
+it already controls a T+ account, and guiding account creation when needed.
+
+From the repo root:
+
+```text
+codex
+/skills
+```
+
+Choose `onboard`, or invoke it directly with:
+
+```text
+$onboard onboard me to T+
+```
+
+The flow reads `TPLUS_PRIVATE_KEY` and `TPLUS_API_BASE_URL` from `.env`. Do not
+paste private keys into chat.
+
 ## CLI
 
 `tpluspy` installs a `tplus` command for interacting with T+ services from the

{tpluspy-0.2.1 → tpluspy-0.2.4}/README.md

@@ -10,6 +10,28 @@ To install, use either `pip` or `uv pip`:
 uv pip install -e .
 ```
 
+## Onboarding with Codex CLI
+
+This repo includes a Codex-discoverable onboarding skill at
+`.agents/skills/onboard` for connecting an EVM wallet key to T+, checking whether
+it already controls a T+ account, and guiding account creation when needed.
+
+From the repo root:
+
+```text
+codex
+/skills
+```
+
+Choose `onboard`, or invoke it directly with:
+
+```text
+$onboard onboard me to T+
+```
+
+The flow reads `TPLUS_PRIVATE_KEY` and `TPLUS_API_BASE_URL` from `.env`. Do not
+paste private keys into chat.
+
 ## CLI
 
 `tpluspy` installs a `tplus` command for interacting with T+ services from the

{tpluspy-0.2.1 → tpluspy-0.2.4}/setup.py

@@ -8,7 +8,7 @@ long_description = (here / "README.md").read_text(encoding="utf-8")
 
 setup(
     name="tpluspy",
-    version="0.2.1",
+    version="0.2.4",
     description="""tpluspy: Client utilities for interacting with tplus""",
     long_description=long_description,
     long_description_content_type="text/markdown",

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/_cli/_context.py

@@ -1,11 +1,14 @@
+import os
 from collections.abc import Callable
 from functools import cached_property
 from pathlib import Path
 from typing import TYPE_CHECKING
+from urllib.parse import urlsplit, urlunsplit
 
 import click
 
 if TYPE_CHECKING:
+    from tplus.client.blockchain import BlockchainClient
     from tplus.client.clearingengine import ClearingEngineClient
     from tplus.client.market_data import MarketDataClient
     from tplus.client.orderbook import OrderBookClient
@@ -17,15 +20,42 @@ if TYPE_CHECKING:
 _AUTH_CACHE_DIR = Path.home() / ".tplus" / "auth"
 
 
+def _derive_market_data_base_url(oms_base_url: str) -> str:
+    """Derive the market-data-service URL from the OMS URL (swap the host label
+    ``oms``->``mds``). Returns the input unchanged for non-oms hosts (e.g. localhost)."""
+    parsed = urlsplit(oms_base_url)
+    host = parsed.hostname
+    if host is None:
+        return oms_base_url
+    if host.startswith("oms."):
+        mds_host = f"mds.{host.removeprefix('oms.')}"
+    elif host.startswith("oms-"):
+        mds_host = f"mds-{host.removeprefix('oms-')}"
+    else:
+        return oms_base_url
+    userinfo = ""
+    if parsed.username is not None:
+        userinfo = parsed.username
+        if parsed.password is not None:
+            userinfo = f"{userinfo}:{parsed.password}"
+        userinfo = f"{userinfo}@"
+    port = f":{parsed.port}" if parsed.port is not None else ""
+    return urlunsplit(
+        (parsed.scheme, f"{userinfo}{mds_host}{port}", parsed.path, parsed.query, parsed.fragment)
+    )
+
+
 # ``dict`` base mirrors ``ape.cli.options.ApeCliContextObject`` so ape's
 # ``network_option`` callback can do ``ctx.obj["network"] = value`` without
 # importing ape here (which would slow down ``tplus --help``).
 class CLIContext(dict):
     def __init__(self):
         super().__init__()
+        self.api_base_url: str | None = None
         self.orderbook_base_url: str | None = None
         self.clearing_base_url: str | None = None
         self.market_data_base_url: str | None = None
+        self.blockchain_base_url: str | None = None
         self.account: str | None = None
         self.ignore_ssl: bool = False
 
@@ -49,22 +79,44 @@ class CLIContext(dict):
         manager = self.user_manager
         return manager._default_user or next(iter(manager.usernames), None)
 
-    def orderbook_client(
-        self, alias: str | None = None, *, anonymous: bool = False
-    ) -> "OrderBookClient":
-        if not self.orderbook_base_url:
+    def _api_base_url(self) -> str | None:
+        """The single T+ base URL (the OMS). Per-service URLs derive from it; an
+        explicit per-service flag / env var overrides it."""
+        return self.api_base_url or os.environ.get("TPLUS_API_BASE_URL")
+
+    def _resolved_orderbook_url(self) -> str:
+        # The OMS host *is* the orderbook service, so TPLUS_API_BASE_URL is used directly.
+        url = self.orderbook_base_url or self._api_base_url()
+        if not url:
+            raise click.UsageError(
+                "No T+ base URL. Set TPLUS_API_BASE_URL (the OMS URL — the single T+ URL "
+                "everything derives from), or pass --orderbook-base-url / set "
+                "TPLUS_ORDERBOOK_BASE_URL to override."
+            )
+        return url
+
+    def _resolved_market_data_url(self) -> str:
+        if self.market_data_base_url:
+            return self.market_data_base_url
+        api = self._api_base_url()
+        if not api:
             raise click.UsageError(
-                "No orderbook base URL specified. "
-                "Pass --orderbook-base-url or set TPLUS_ORDERBOOK_BASE_URL."
+                "No T+ base URL. Set TPLUS_API_BASE_URL (the market-data URL is derived "
+                "by swapping the host label oms->mds), or pass --market-data-base-url / "
+                "set TPLUS_MARKET_DATA_BASE_URL to override."
             )
+        return _derive_market_data_base_url(api)
 
+    def orderbook_client(
+        self, alias: str | None = None, *, anonymous: bool = False
+    ) -> "OrderBookClient":
         from tplus.client.auth import Auth
         from tplus.client.orderbook import OrderBookClient
         from tplus.utils.user.model import User
 
         user = User() if anonymous else self.load_user(alias)
         return OrderBookClient(
-            base_url=self.orderbook_base_url,
+            base_url=self._resolved_orderbook_url(),
             default_user=user,
             auth=Auth(cache_dir=_AUTH_CACHE_DIR),
             insecure_ssl=self.ignore_ssl,
@@ -90,12 +142,7 @@ class CLIContext(dict):
         )
 
     def _oms_base_url(self) -> str:
-        if not self.orderbook_base_url:
-            raise click.UsageError(
-                "No orderbook base URL specified. "
-                "Pass --orderbook-base-url or set TPLUS_ORDERBOOK_BASE_URL."
-            )
-        return self.orderbook_base_url
+        return self._resolved_orderbook_url()
 
     def withdrawal_client(self, alias: str | None = None) -> "WithdrawalClient":
         from tplus.client.withdrawal import WithdrawalClient
@@ -106,17 +153,22 @@ class CLIContext(dict):
             insecure_ssl=self.ignore_ssl,
         )
 
-    def market_data_client(self) -> "MarketDataClient":
-        if not self.market_data_base_url:
+    def blockchain_client(self) -> "BlockchainClient":
+        if not self.blockchain_base_url:
             raise click.UsageError(
-                "No market-data base URL specified. "
-                "Pass --market-data-base-url or set TPLUS_MARKET_DATA_BASE_URL."
+                "No blockchain client base URL specified. "
+                "Pass --blockchain-base-url or set TPLUS_BLOCKCHAIN_BASE_URL."
             )
 
+        from tplus.client.blockchain import BlockchainClient
+
+        return BlockchainClient(base_url=self.blockchain_base_url, insecure_ssl=self.ignore_ssl)
+
+    def market_data_client(self) -> "MarketDataClient":
         from tplus.client.market_data import MarketDataClient
 
         return MarketDataClient(
-            base_url=self.market_data_base_url,
+            base_url=self._resolved_market_data_url(),
             insecure_ssl=self.ignore_ssl,
         )
 
@@ -164,6 +216,16 @@ def market_data_url_option() -> Callable:
     )
 
 
+def blockchain_url_option() -> Callable:
+    return click.option(
+        "--blockchain-base-url",
+        envvar="TPLUS_BLOCKCHAIN_BASE_URL",
+        help="T+ blockchain client base URL.",
+        callback=_set_on_ctx("blockchain_base_url"),
+        expose_value=False,
+    )
+
+
 def tplus_account_option() -> Callable:
     def callback(ctx: click.Context, _param, value):
         cli_ctx = ctx.ensure_object(CLIContext)

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/_cli/debug.py

@@ -2,7 +2,12 @@ import asyncio
 
 import click
 
-from tplus._cli._context import CLIContext, clearing_url_option, pass_cli_context
+from tplus._cli._context import (
+    CLIContext,
+    blockchain_url_option,
+    clearing_url_option,
+    pass_cli_context,
+)
 from tplus.cli_tools import ignore_ssl_option
 
 
@@ -90,6 +95,48 @@ def _set_withdrawal_delay(
     click.echo("Withdrawal delay parameters updated.")
 
 
+@debug.command("sync-vault-events")
+@click.option("--from-block", "from_block", type=int, required=True)
+@click.option("--to-block", "to_block", type=int, required=True)
+@click.option("--address", "address", default=None, help="Contract address to filter on.")
+@click.option(
+    "--event",
+    "events",
+    multiple=True,
+    help="Event topic-0 signature to filter on (repeatable).",
+)
+@click.option(
+    "--operator-secret",
+    "operator_secret",
+    envvar="TPLUS_OPERATOR_SECRET",
+    default=None,
+    help="Hex operator secret. Required by authenticated (threshold) clients.",
+)
+@blockchain_url_option()
+@ignore_ssl_option()
+@pass_cli_context
+def _sync_vault_events(
+    cli_ctx: CLIContext,
+    from_block: int,
+    to_block: int,
+    address: str | None,
+    events: tuple[str, ...],
+    operator_secret: str | None,
+):
+    """Re-ingest a blockchain client's on-chain events in a block range."""
+    client = cli_ctx.blockchain_client()
+    asyncio.run(
+        client.sync_vault_events(
+            from_block,
+            to_block,
+            address=address,
+            events=list(events) or None,
+            operator_secret=operator_secret,
+        )
+    )
+    click.echo(f"Requested re-ingestion of blocks {from_block}-{to_block}.")
+
+
 @debug.command("reset-users")
 @clearing_url_option()
 @ignore_ssl_option()

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/_cli/env.py

@@ -20,7 +20,17 @@ def env(output_format: str):
     """Show CLI-relevant environment variables and their current values."""
     entries: list[tuple[str, str, str]] = [
         ("TPLUS_ACCOUNT", _default_account(), "Default local account alias."),
-        ("TPLUS_ORDERBOOK_BASE_URL", "", "Orderbook service base URL."),
+        (
+            "TPLUS_API_BASE_URL",
+            "",
+            "Single T+ base URL (OMS); orderbook + market-data derive from it.",
+        ),
+        ("TPLUS_ORDERBOOK_BASE_URL", "", "Override: orderbook service base URL."),
+        (
+            "TPLUS_MARKET_DATA_BASE_URL",
+            "",
+            "Override: market-data URL (else derived from API URL, oms->mds).",
+        ),
         ("TPLUS_CLEARING_BASE_URL", "", "Clearing engine base URL."),
         ("TPLUS_IGNORE_SSL", "false", "Skip TLS certificate verification."),
         ("TPLUS_OUTPUT_FORMAT", "table", "Default output format (table | json)."),

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/_cli/markets.py

@@ -11,6 +11,7 @@ from tplus._cli._context import (
     pass_cli_context,
     tplus_account_option,
 )
+from tplus.asset_metadata import asset_metadata_dict
 from tplus.cli_tools import (
     echo_with_pager,
     ignore_ssl_option,
@@ -71,9 +72,13 @@ def _list(cli_ctx: CLIContext, output_format: str, no_pager: bool):
     records = []
     for market in response or []:
         fee_schedule = market.get("fee_schedule") or {}
+        asset_metadata = asset_metadata_dict(market.get("asset_id")) or {}
         records.append(
             {
                 "asset_id": market.get("asset_id"),
+                "symbol": asset_metadata.get("symbol"),
+                "asset_class": asset_metadata.get("asset_class"),
+                "representations": asset_metadata.get("representations"),
                 "price_decimals": market.get("book_price_decimals"),
                 "quantity_decimals": market.get("book_quantity_decimals"),
                 "max_leverage": market.get("max_leverage"),
@@ -136,9 +141,9 @@ def _klines(
     )
     if output_format == "raw":
         echo_with_pager(
-            [kline.model_dump_json() for kline in klines],
+            [kline.model_dump_json() for kline in klines.items],
             no_pager=no_pager,
         )
         return
 
-    render([kline.model_dump() for kline in klines], output_format, no_pager=no_pager)
+    render([kline.model_dump() for kline in klines.items], output_format, no_pager=no_pager)

tpluspy-0.2.4/tplus/asset_metadata.py

@@ -0,0 +1,116 @@
+"""Static T+ asset metadata used for display-only symbol resolution.
+
+The protocol identifies assets by ``AssetIdentifier`` values, not symbols. This
+module is a temporary local snapshot so CLI and onboarding output can show the
+canonical symbol next to known production indexes and chain-address aliases.
+
+Source snapshot: ``tplus-risk-params`` ``main:environments/prod/params.json``.
+Do not use this for risk checks; read live registry/market endpoints for trading
+parameters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from tplus.model.asset_identifier import AssetIdentifier
+
+
+@dataclass(frozen=True)
+class AssetMetadata:
+    index: int
+    symbol: str
+    asset_class: str
+    representations: tuple[str, ...]
+
+
+CANONICAL_ASSETS: dict[int, AssetMetadata] = {
+    0: AssetMetadata(0, "USDC", "USD", ("USDC", "USDT")),
+    1: AssetMetadata(1, "ETH", "ETH", ("WETH",)),
+    2: AssetMetadata(2, "BTC", "BTC", ("WBTC",)),
+    3: AssetMetadata(3, "ARB", "ARB", ("ARB",)),
+    4: AssetMetadata(4, "MON", "MON", ("MON",)),
+    5: AssetMetadata(5, "GOLD", "GOLD", ("XAUT",)),
+    6: AssetMetadata(6, "CIGS", "CIGS", ("CIGS",)),
+}
+
+
+CHAIN_ASSET_INDEXES: dict[str, int] = {
+    # USDC / USDT -> USD class.
+    "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48000000000000000000000000@000000000000000001": 0,
+    "af88d065e77c8cc2239327c5edb3a432268e5831000000000000000000000000@00000000000000a4b1": 0,
+    "754704bc059f8c67012fed69bc8a327a5aafb603000000000000000000000000@00000000000000008f": 0,
+    "dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000@000000000000000001": 0,
+    "833589fcd6edb6e08f4c7c32d4f71b54bda02913000000000000000000000000@000000000000002105": 0,
+    # ETH.
+    "82af49447d8a07e3bd95bd0d56f35241523fbab1000000000000000000000000@00000000000000a4b1": 1,
+    "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000@000000000000000001": 1,
+    "ee8c0e9f1bffb4eb878d8f15f368a02a35481242000000000000000000000000@00000000000000008f": 1,
+    "4200000000000000000000000000000000000006000000000000000000000000@000000000000002105": 1,
+    # BTC.
+    "2260fac5e5542a773aa44fbcfedf7c193bc2c599000000000000000000000000@000000000000000001": 2,
+    "2f2a2543b76a4166549f7aab2e75bef0aefc5b0f000000000000000000000000@00000000000000a4b1": 2,
+    "0555e30da8f98308edb960aa94c0db47230d2b9c000000000000000000000000@00000000000000008f": 2,
+    # ARB.
+    "b50721bcf8d664c30412cfbc6cf7a15145234ad1000000000000000000000000@000000000000000001": 3,
+    "912ce59144191c1204e64559fe8253a0e49e6548000000000000000000000000@00000000000000a4b1": 3,
+    # MON.
+    "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000@00000000000000008f": 4,
+    # GOLD / XAUT.
+    "68749665ff8d2d112fa859aa293f07a622782f38000000000000000000000000@000000000000000001": 5,
+    # CIGS.
+    "2e9126f66e386879f312287a419b0f70004c3f5b000000000000000000000000@000000000000002105": 6,
+}
+
+
+def _asset_id_key(asset_id: Any) -> str:
+    if isinstance(asset_id, AssetIdentifier):
+        return str(asset_id)
+    if isinstance(asset_id, int):
+        return str(asset_id)
+    if isinstance(asset_id, dict):
+        return str(AssetIdentifier.model_validate(asset_id))
+    return str(asset_id).lower().removeprefix("0x")
+
+
+def asset_index(asset_id: Any) -> int | None:
+    """Return the canonical asset index for a known index/address identifier."""
+    key = _asset_id_key(asset_id)
+    if key.isnumeric():
+        return int(key)
+    if "@" in key:
+        try:
+            key = str(AssetIdentifier(key))
+        except ValueError:
+            pass
+        return CHAIN_ASSET_INDEXES.get(key)
+    return None
+
+
+def get_asset_metadata(asset_id: Any) -> AssetMetadata | None:
+    index = asset_index(asset_id)
+    if index is None:
+        return None
+    return CANONICAL_ASSETS.get(index)
+
+
+def asset_label(asset_id: Any) -> str:
+    """Human label for a known asset identifier, falling back without guessing."""
+    key = _asset_id_key(asset_id)
+    metadata = get_asset_metadata(key)
+    if metadata is None:
+        return f"asset {key}"
+    return f"{metadata.symbol} (asset {key})"
+
+
+def asset_metadata_dict(asset_id: Any) -> dict[str, Any] | None:
+    metadata = get_asset_metadata(asset_id)
+    if metadata is None:
+        return None
+    return {
+        "index": metadata.index,
+        "symbol": metadata.symbol,
+        "asset_class": metadata.asset_class,
+        "representations": list(metadata.representations),
+    }

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/client/__init__.py

@@ -1,3 +1,4 @@
+from .blockchain import BlockchainClient
 from .clearingengine import ClearingEngineClient
 from .market_data import MarketDataClient
 from .oms import AssetRegistryClient
@@ -5,6 +6,7 @@ from .orderbook import OrderBookClient
 from .withdrawal import WithdrawalClient
 
 __all__ = (
+    "BlockchainClient",
     "ClearingEngineClient",
     "MarketDataClient",
     "OrderBookClient",

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/client/base.py

@@ -178,10 +178,9 @@ class BaseClient:
         user: "UserType | None" = None,
         request_timeout: float | None = None,
     ) -> dict[str, Any]:
-        relative_url = endpoint if endpoint.startswith("/") else f"/{endpoint}"
         response = await self._send(
             method,
-            relative_url,
+            endpoint,
             json_data=json_data,
             params=params,
             request_timeout=request_timeout,
@@ -201,6 +200,7 @@ class BaseClient:
         headers: dict[str, str] | None = None,
         request_timeout: float | None = None,
     ) -> httpx.Response:
+        relative_url = relative_url if relative_url.startswith("/") else f"/{relative_url}"
         if json_data or params:
             self.logger.debug(
                 f"Request to {method} {relative_url} with payload: {json_data} params: {params}"

tpluspy-0.2.4/tplus/client/blockchain.py

@@ -0,0 +1,50 @@
+import time
+
+from tplus.client.base import BaseClient
+from tplus.utils.operator import load_operator_sk, sign_operator_payload
+
+
+class BlockchainClient(BaseClient):
+    """Admin HTTP client for a blockchain client (threshold / anvil).
+
+    Authenticates with a secp256k1 operator signature rather than Ed25519 user signing.
+    ``base_url`` points at the blockchain client's health-API port.
+    """
+
+    async def sync_vault_events(
+        self,
+        from_block: int,
+        to_block: int,
+        *,
+        address: str | None = None,
+        events: list[str] | None = None,
+        operator_secret: str | None = None,
+        timestamp_ms: int | None = None,
+    ) -> None:
+        """Trigger re-ingestion of on-chain events in ``[from_block, to_block]``.
+
+        Fire-and-forget: the client re-queries logs and replays them over the overlay, so nothing
+        is returned here. Pass ``operator_secret`` for authenticated (threshold) clients; omit it
+        for anvil.
+        """
+        timestamp = int(time.time() * 1000) if timestamp_ms is None else timestamp_ms
+        events_str = ",".join(events) if events else ""
+        payload = f"{from_block}:{to_block}:{timestamp}:{address or ''}:{events_str}".encode()
+
+        signature = ""
+        if operator_secret is not None:
+            signature = sign_operator_payload(payload, load_operator_sk(operator_secret))
+
+        body: dict = {
+            "from_block": from_block,
+            "to_block": to_block,
+            "timestamp": timestamp,
+            "signature": signature,
+        }
+        if address is not None:
+            body["address"] = address
+        if events is not None:
+            body["events"] = events
+
+        # "historical_logs" is the blockchain client's existing route name.
+        await self._post("historical_logs", json_data=body, requires_auth=False)

{tpluspy-0.2.1 → tpluspy-0.2.4}/tplus/client/clearingengine/__init__.py

@@ -5,6 +5,7 @@ from tplus.client.clearingengine.admin import AdminClient
 from tplus.client.clearingengine.admin_settlement import AdminSettlementClient
 from tplus.client.clearingengine.assetregistry import AdminAssetRegistryClient
 from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.client.clearingengine.cross_venue import CrossVenueClient
 from tplus.client.clearingengine.decimal import DecimalClient
 from tplus.client.clearingengine.vault import VaultClient
 
@@ -50,6 +51,13 @@ class ClearingEngineClient(BaseClearingEngineClient):
         """
         return VaultClient.from_client(self)
 
+    @cached_property
+    def cross_venue(self) -> CrossVenueClient:
+        """
+        User-facing cross-venue (Hyperliquid) margin APIs.
+        """
+        return CrossVenueClient.from_client(self)
+
     @cached_property
     def admin(self) -> AdminClient:
         """