tpluspy 0.3.2__tar.gz → 0.5.0__tar.gz

{tpluspy-0.3.2 → tpluspy-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpluspy
-Version: 0.3.2
+Version: 0.5.0
 Summary: tpluspy: Client utilities for interacting with tplus
 Home-page: https://github.com/tpluslabs/tpluspy
 Author: TPlus Labs
@@ -29,6 +29,7 @@ Requires-Dist: pycryptodome>=3.17.1
 Requires-Dist: pydantic<3,>=2.10.4
 Requires-Dist: websockets<14,>=13.1
 Provides-Extra: test
+Requires-Dist: eth-account<0.14,>=0.13.0; extra == "test"
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: pytest-timeout<3,>=2.2.0; extra == "test"
 Requires-Dist: pytest-mock; extra == "test"
@@ -36,6 +37,7 @@ Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: anyio>=4; extra == "test"
 Requires-Dist: pytest-anyio>=0.0.0; extra == "test"
 Requires-Dist: trio>=0.24; extra == "test"
+Requires-Dist: eth-tester[py-evm]>=0.12.0b1; extra == "test"
 Provides-Extra: lint
 Requires-Dist: ruff<0.16,>=0.11.7; extra == "lint"
 Requires-Dist: mypy<2,>=1.18.2; extra == "lint"
@@ -44,11 +46,17 @@ Requires-Dist: setuptools>=75.6.0; extra == "release"
 Requires-Dist: wheel; extra == "release"
 Requires-Dist: twine; extra == "release"
 Provides-Extra: evm
-Requires-Dist: ape-tokens; extra == "evm"
 Requires-Dist: click; extra == "evm"
 Requires-Dist: eip712>=0.3.1; extra == "evm"
-Requires-Dist: eth-ape<0.9,>=0.8.49; extra == "evm"
+Requires-Dist: eth-account<0.14,>=0.13.0; extra == "evm"
+Requires-Dist: eth-keys<0.8,>=0.6; extra == "evm"
 Requires-Dist: hexbytes<2,>=1.3.1; extra == "evm"
+Requires-Dist: pyyaml<7,>=6; extra == "evm"
+Requires-Dist: web3<8,>=7.0; extra == "evm"
+Provides-Extra: evm-ape
+Requires-Dist: tpluspy[evm]; extra == "evm-ape"
+Requires-Dist: ape-tokens; extra == "evm-ape"
+Requires-Dist: eth-ape<0.9,>=0.8.49; extra == "evm-ape"
 Provides-Extra: docs
 Requires-Dist: Sphinx<9,>=7.0; extra == "docs"
 Requires-Dist: myst-parser<5,>=2.0; extra == "docs"
@@ -142,6 +150,41 @@ async def run_client():
 asyncio.run(run_client())
 ```
 
+#### Use EVM accounts as T+ accounts
+
+An EVM account can back a T+ account: it signs one fixed message and the T+ identity is derived from that signature, so the same wallet always maps to the same T+ account (the one the T+ frontend derives on wallet login).
+
+Pass the account itself anywhere a `User` is accepted, whether that is `default_user=`, a per-call `user=`, or a `signer=`:
+
+```python
+from ape import accounts
+
+account = accounts.load("me")
+
+async with OrderBookClient(API_BASE_URL, default_user=account) as client:
+    await client.get_user_inventory()  # signs as the T+ user behind the account
+    await client.create_limit_order(..., user=account)  # per-call override
+```
+
+An `eth_account` signer works the same way, with no `[evm]` extra:
+
+```python
+from eth_account import Account
+
+client = OrderBookClient(API_BASE_URL, default_user=Account.from_key("0x..."))
+```
+
+Use `load_user_from_ape_account` to hold the `User` itself, for example to read its public key or to pick a sub-account. `load_user` loads stored keyfiles by name, so Ape aliases and keyfile names occupy separate namespaces and cannot collide:
+
+```python
+from tplus.utils.user import load_user_from_ape_account
+
+user = load_user_from_ape_account("me")  # by Ape alias (needs the `evm` extra)
+user = load_user_from_ape_account(account)  # an already-loaded Ape account
+```
+
+The result is a normal T+ `User` and signs every request the same way.
+
 #### REST API Usage
 
 The client offers async methods for common REST endpoints:
@@ -225,13 +268,28 @@ print(f"Cancel Order Response: {cancel_response}")
 # Replace an Order
 # Original Order ID should be from an existing, open order.
 original_order_id_to_replace = "actual-original-order-id"  # Replace with a real order ID
-replace_response = await client.replace_order(
+replace_response, revision = await client.replace_order(
     original_order_id=original_order_id_to_replace,
     asset_id=example_asset,
-    new_quantity=6,  # Optional: New integer quantity
-    new_price=1050,  # Optional: New integer price
+    new_quantity=6,  # Effective lifetime-total quantity
+    new_price=1050,  # Effective limit price
 )
 print(f"Replace Order Response: {replace_response}")
+# `revision` is the replacement's timestamp_ns; a later amend_order must quote it as
+# expected_authorization_revision.
+
+# Replace several open orders in one request (up to 50). Each item is signed on its own;
+# the OMS sends one message per market and returns one status per item, in order.
+batch_replace_response = await client.replace_multiple_orders(
+    [
+        await client.prepare_replace_order_request(
+            original_order_id=oid, asset_id=example_asset, new_quantity=6, new_price=price
+        )
+        for oid, price in [("order-a", 1050), ("order-b", 1040)]
+    ]
+)
+for status in batch_replace_response.batch_order_status:
+    print(f"{status.order_id}: {status.status} {status.reason or ''}")
 ```
 
 See `examples/rest_usage.py` for a runnable demonstration.
@@ -269,68 +327,55 @@ async for trade in client.stream_finalized_trades():
 
 See `examples/websocket_usage.py` for a runnable demonstration using `asyncio.gather` to run multiple streams concurrently.
 
+#### Token Recovery
+
+When a bearer token stops working before it actually expires (e.g. from a service restart), both transports recover on their own. A REST response or WebSocket handshake rejected with `401` or `403` re-authenticates and retries once; a second rejection is raised to the caller. Requests rejected concurrently share a single re-authentication.
+
 ### Contracts
 
-To interact with the contracts or sign T+ settlement messages, ensure you have installed the `evm` extra:
+To interact with the on-chain T+ contracts (or sign T+ settlement messages),
+install one of the EVM extras:
 
 ```shell
-pip install tpluspy[evm]
+pip install "tpluspy[evm]"        # web3.py backend (no Ape)
+pip install "tpluspy[evm-ape]"    # adds the Ape backend on top of [evm]
 ```
 
-Use the `tplusp.contracts` module to read data from t+ contracts.
-For example, launch a Sepolia-connected Ape console:
+The Python API is identical either way. With the **web3.py** backend, point it
+at a node via `WEB3_PROVIDER_URI` (read by `web3.auto`) — or call
+`tplus.evm.use_web3(rpc_url=...)`:
 
 ```shell
-ape console --network ethereum:sepolia:alchemy
+export WEB3_PROVIDER_URI="https://arb1.arbitrum.io/rpc"
+```
+
+```python
+from tplus.evm.contracts import registry, vault
+
+registry.admin()
+vault.getApprovedSettlers()
 ```
 
-**Note**: You can use any provider you want or a RPC directly, it doesn't have to be Alchemy.
+With the **Ape** backend, just use `ape console` / `ape run` as usual; it's
+auto-detected whenever Ape is connected to a network:
 
-Then, once in the console, you will already have access to contracts that you can call methods on:
+```shell
+ape console --network ethereum:sepolia:alchemy
+```
 
 ```python
-In[1]: registry.getAssets()
-Out[1]: [
+In [1]: from tplus.evm.contracts import registry
+In [2]: registry.getAssets()
+Out[2]: [
     getAssets_return(
         assetAddress=HexBytes("0x000000000000000000000000f08a50178dfcde18524640ea6618a1f965821715"),
         chainId=11155111,
         maxDeposits=100,
     )
 ]
-In[2]: registry.admin()
-Out[2]: "0x467a95fC5359edE5d5dDc4f10A1F4B680694858E"
+In [3]: registry.admin()
+Out[3]: '0x467a95fC5359edE5d5dDc4f10A1F4B680694858E'
 ```
 
-#### Settlement signatures
-
-Sign settlement messages using the structured `Order` type from `tplus.utils.domain`.
-
-```python
-from ape import accounts, convert, chain
-from tplus.utils.domain import Order
-from tplus.evm.contracts import vault
-from tplus.utils.user import UserManager
-
-# Load your Ethereum account for t+.
-tplus_user = accounts.load("tplus-account")
-
-# Load your t+ user (public key).
-user_id = UserManager.load("my_user").public_key
-
-# Get the nonce from t+ or the contracts directly.
-nonce = vault.getDepositNonce(tplus_user)
-
-order = Order(
-    tokenOut="0x62622E77D1349Face943C6e7D5c01C61465FE1dc",
-    amountOut=convert("1 ether", int),
-    tokenIn="0x58372ab62269A52fA636aD7F200d93999595DCAF",
-    amountIn=convert("1 ether", int),
-    userId=user_id,
-    nonce=nonce,
-    validUntil=chain.pending_timestamp,
-)
-
-# Use this signature for the settlement.
-signature = tplus_user.sign_message(order).encode_rsv()
-print(signature)
-```
+See [`docs/userguides/contracts.md`](docs/userguides/contracts.md) for the full
+guide, including accounts, settlements, and the higher-level managers.

{tpluspy-0.3.2 → tpluspy-0.5.0}/README.md

@@ -71,6 +71,41 @@ async def run_client():
 asyncio.run(run_client())
 ```
 
+#### Use EVM accounts as T+ accounts
+
+An EVM account can back a T+ account: it signs one fixed message and the T+ identity is derived from that signature, so the same wallet always maps to the same T+ account (the one the T+ frontend derives on wallet login).
+
+Pass the account itself anywhere a `User` is accepted, whether that is `default_user=`, a per-call `user=`, or a `signer=`:
+
+```python
+from ape import accounts
+
+account = accounts.load("me")
+
+async with OrderBookClient(API_BASE_URL, default_user=account) as client:
+    await client.get_user_inventory()  # signs as the T+ user behind the account
+    await client.create_limit_order(..., user=account)  # per-call override
+```
+
+An `eth_account` signer works the same way, with no `[evm]` extra:
+
+```python
+from eth_account import Account
+
+client = OrderBookClient(API_BASE_URL, default_user=Account.from_key("0x..."))
+```
+
+Use `load_user_from_ape_account` to hold the `User` itself, for example to read its public key or to pick a sub-account. `load_user` loads stored keyfiles by name, so Ape aliases and keyfile names occupy separate namespaces and cannot collide:
+
+```python
+from tplus.utils.user import load_user_from_ape_account
+
+user = load_user_from_ape_account("me")  # by Ape alias (needs the `evm` extra)
+user = load_user_from_ape_account(account)  # an already-loaded Ape account
+```
+
+The result is a normal T+ `User` and signs every request the same way.
+
 #### REST API Usage
 
 The client offers async methods for common REST endpoints:
@@ -154,13 +189,28 @@ print(f"Cancel Order Response: {cancel_response}")
 # Replace an Order
 # Original Order ID should be from an existing, open order.
 original_order_id_to_replace = "actual-original-order-id"  # Replace with a real order ID
-replace_response = await client.replace_order(
+replace_response, revision = await client.replace_order(
     original_order_id=original_order_id_to_replace,
     asset_id=example_asset,
-    new_quantity=6,  # Optional: New integer quantity
-    new_price=1050,  # Optional: New integer price
+    new_quantity=6,  # Effective lifetime-total quantity
+    new_price=1050,  # Effective limit price
 )
 print(f"Replace Order Response: {replace_response}")
+# `revision` is the replacement's timestamp_ns; a later amend_order must quote it as
+# expected_authorization_revision.
+
+# Replace several open orders in one request (up to 50). Each item is signed on its own;
+# the OMS sends one message per market and returns one status per item, in order.
+batch_replace_response = await client.replace_multiple_orders(
+    [
+        await client.prepare_replace_order_request(
+            original_order_id=oid, asset_id=example_asset, new_quantity=6, new_price=price
+        )
+        for oid, price in [("order-a", 1050), ("order-b", 1040)]
+    ]
+)
+for status in batch_replace_response.batch_order_status:
+    print(f"{status.order_id}: {status.status} {status.reason or ''}")
 ```
 
 See `examples/rest_usage.py` for a runnable demonstration.
@@ -198,68 +248,55 @@ async for trade in client.stream_finalized_trades():
 
 See `examples/websocket_usage.py` for a runnable demonstration using `asyncio.gather` to run multiple streams concurrently.
 
+#### Token Recovery
+
+When a bearer token stops working before it actually expires (e.g. from a service restart), both transports recover on their own. A REST response or WebSocket handshake rejected with `401` or `403` re-authenticates and retries once; a second rejection is raised to the caller. Requests rejected concurrently share a single re-authentication.
+
 ### Contracts
 
-To interact with the contracts or sign T+ settlement messages, ensure you have installed the `evm` extra:
+To interact with the on-chain T+ contracts (or sign T+ settlement messages),
+install one of the EVM extras:
 
 ```shell
-pip install tpluspy[evm]
+pip install "tpluspy[evm]"        # web3.py backend (no Ape)
+pip install "tpluspy[evm-ape]"    # adds the Ape backend on top of [evm]
 ```
 
-Use the `tplusp.contracts` module to read data from t+ contracts.
-For example, launch a Sepolia-connected Ape console:
+The Python API is identical either way. With the **web3.py** backend, point it
+at a node via `WEB3_PROVIDER_URI` (read by `web3.auto`) — or call
+`tplus.evm.use_web3(rpc_url=...)`:
 
 ```shell
-ape console --network ethereum:sepolia:alchemy
+export WEB3_PROVIDER_URI="https://arb1.arbitrum.io/rpc"
+```
+
+```python
+from tplus.evm.contracts import registry, vault
+
+registry.admin()
+vault.getApprovedSettlers()
 ```
 
-**Note**: You can use any provider you want or a RPC directly, it doesn't have to be Alchemy.
+With the **Ape** backend, just use `ape console` / `ape run` as usual; it's
+auto-detected whenever Ape is connected to a network:
 
-Then, once in the console, you will already have access to contracts that you can call methods on:
+```shell
+ape console --network ethereum:sepolia:alchemy
+```
 
 ```python
-In[1]: registry.getAssets()
-Out[1]: [
+In [1]: from tplus.evm.contracts import registry
+In [2]: registry.getAssets()
+Out[2]: [
     getAssets_return(
         assetAddress=HexBytes("0x000000000000000000000000f08a50178dfcde18524640ea6618a1f965821715"),
         chainId=11155111,
         maxDeposits=100,
     )
 ]
-In[2]: registry.admin()
-Out[2]: "0x467a95fC5359edE5d5dDc4f10A1F4B680694858E"
+In [3]: registry.admin()
+Out[3]: '0x467a95fC5359edE5d5dDc4f10A1F4B680694858E'
 ```
 
-#### Settlement signatures
-
-Sign settlement messages using the structured `Order` type from `tplus.utils.domain`.
-
-```python
-from ape import accounts, convert, chain
-from tplus.utils.domain import Order
-from tplus.evm.contracts import vault
-from tplus.utils.user import UserManager
-
-# Load your Ethereum account for t+.
-tplus_user = accounts.load("tplus-account")
-
-# Load your t+ user (public key).
-user_id = UserManager.load("my_user").public_key
-
-# Get the nonce from t+ or the contracts directly.
-nonce = vault.getDepositNonce(tplus_user)
-
-order = Order(
-    tokenOut="0x62622E77D1349Face943C6e7D5c01C61465FE1dc",
-    amountOut=convert("1 ether", int),
-    tokenIn="0x58372ab62269A52fA636aD7F200d93999595DCAF",
-    amountIn=convert("1 ether", int),
-    userId=user_id,
-    nonce=nonce,
-    validUntil=chain.pending_timestamp,
-)
-
-# Use this signature for the settlement.
-signature = tplus_user.sign_message(order).encode_rsv()
-print(signature)
-```
+See [`docs/userguides/contracts.md`](docs/userguides/contracts.md) for the full
+guide, including accounts, settlements, and the higher-level managers.

{tpluspy-0.3.2 → tpluspy-0.5.0}/setup.py

@@ -8,7 +8,7 @@ long_description = (here / "README.md").read_text(encoding="utf-8")
 
 setup(
     name="tpluspy",
-    version="0.3.2",
+    version="0.5.0",
     description="""tpluspy: Client utilities for interacting with tplus""",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -34,6 +34,7 @@ setup(
     python_requires=">=3.10,<4",
     extras_require={
         "test": [
+            "eth-account>=0.13.0,<0.14",
             "pytest>=8.0",
             "pytest-timeout>=2.2.0,<3",
             "pytest-mock",
@@ -41,6 +42,10 @@ setup(
             "anyio>=4",
             "pytest-anyio>=0.0.0",
             "trio>=0.24",
+            # In-process EVM backend used by the web3-backend tests. ``py-evm``
+            # is what actually executes the EVM; ``eth-tester`` only ships
+            # pre-releases on PyPI so allow them.
+            "eth-tester[py-evm]>=0.12.0b1",
         ],
         "lint": [
             "ruff>=0.11.7,<0.16",
@@ -52,11 +57,18 @@ setup(
             "twine",
         ],
         "evm": [
-            "ape-tokens",
             "click",
             "eip712>=0.3.1",
-            "eth-ape>=0.8.49,<0.9",
+            "eth-account>=0.13.0,<0.14",
+            "eth-keys>=0.6,<0.8",
             "hexbytes>=1.3.1,<2",
+            "pyyaml>=6,<7",
+            "web3>=7.0,<8",
+        ],
+        "evm-ape": [
+            "tpluspy[evm]",
+            "ape-tokens",
+            "eth-ape>=0.8.49,<0.9",
         ],
         "docs": [
             "Sphinx>=7.0,<9",
@@ -72,7 +84,7 @@ setup(
     zip_safe=False,
     keywords="ethereum",
     packages=find_packages(exclude=["tests", "tests.*"]),
-    package_data={"tpluspy": ["py.typed", "evm/manifests/*"]},
+    package_data={"tplus": ["py.typed", "evm/manifests/*"]},
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",

{tpluspy-0.3.2 → tpluspy-0.5.0}/tplus/_cli/_context.py

@@ -73,6 +73,7 @@ class CLIContext(dict):
                 "Pass --tplus-account, set TPLUS_ACCOUNT, "
                 "or create one with `tplus accounts add`."
             )
+
         return self.user_manager.load(name)
 
     def _resolve_default_account(self) -> str | None:

{tpluspy-0.3.2 → tpluspy-0.5.0}/tplus/_cli/markets.py

@@ -1,6 +1,5 @@
 import asyncio
 import json
-from typing import Any, cast
 
 import click
 
@@ -19,6 +18,23 @@ from tplus.cli_tools import (
     output_format_option,
     render,
 )
+from tplus.model.market import MarketResponse
+
+
+async def _collect_markets(
+    client, page_number: int | None, limit: int | None
+) -> list[MarketResponse]:
+    """The requested page, or every page when the caller did not pick one."""
+    page = await client.get_markets(page=page_number, limit=limit)
+    if page_number is not None:
+        return page.markets
+
+    markets = list(page.markets)
+    while page.next_page is not None:
+        page = await client.get_markets(page=page.next_page, limit=limit)
+        markets.extend(page.markets)
+
+    return markets
 
 
 @click.group()
@@ -60,35 +76,43 @@ def _get(cli_ctx: CLIContext, asset_id: str):
 @tplus_account_option()
 @output_format_option()
 @no_pager_option()
+@click.option("--page", "page_number", type=int)
+@click.option("--limit", type=int)
 @pass_cli_context
-def _list(cli_ctx: CLIContext, output_format: str, no_pager: bool):
-    """List all markets."""
+def _list(
+    cli_ctx: CLIContext,
+    output_format: str,
+    no_pager: bool,
+    page_number: int | None,
+    limit: int | None,
+):
+    """List all markets, following pagination unless `--page` picks one."""
     client = cli_ctx.orderbook_client()
-    response = cast("list[dict[str, Any]]", asyncio.run(client._request("GET", "/markets")))
+    markets = asyncio.run(_collect_markets(client, page_number, limit))
     if output_format == "raw":
-        click.echo(json.dumps(response, indent=2, default=str))
+        raw = [market.model_dump(by_alias=True) for market in markets]
+        click.echo(json.dumps(raw, indent=2, default=str))
         return
 
     records = []
-    for market in response or []:
-        fee_schedule = market.get("fee_schedule") or {}
-        asset_metadata = asset_metadata_dict(market.get("asset_id")) or {}
+    for market in markets:
+        fee_schedule = market.fee_schedule
+        asset_metadata = asset_metadata_dict(str(market.asset_id)) or {}
         records.append(
             {
-                "asset_id": market.get("asset_id"),
+                "asset_id": str(market.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"),
-                "isolated_only": market.get("isolated_only"),
-                "tick_size": market.get("tick_size"),
-                "min_order_size": market.get("min_order_size"),
-                "fee_account": fee_schedule.get("fee_account"),
+                "price_decimals": market.book_price_decimals,
+                "quantity_decimals": market.book_quantity_decimals,
+                "max_leverage": market.max_leverage,
+                "isolated_only": market.isolated_only,
+                "tick_size": market.tick_size,
+                "min_order_size": market.min_order_size,
+                "fee_account": fee_schedule.fee_account if fee_schedule else None,
                 "fee_tiers": (
-                    f"{len(fee_schedule.get('global') or [])} global / "
-                    f"{len(fee_schedule.get('per_asset') or [])} per-asset"
+                    f"{len(fee_schedule.global_)} global / {len(fee_schedule.per_asset)} per-asset"
                     if fee_schedule
                     else None
                 ),
@@ -97,6 +121,35 @@ def _list(cli_ctx: CLIContext, output_format: str, no_pager: bool):
     render(records, output_format, no_pager=no_pager)
 
 
+@markets.command("symbol-map")
+@orderbook_url_option()
+@ignore_ssl_option()
+@tplus_account_option()
+@output_format_option()
+@no_pager_option()
+@pass_cli_context
+def _symbol_map(cli_ctx: CLIContext, output_format: str, no_pager: bool):
+    """Show the canonical asset table served by the OMS."""
+    client = cli_ctx.orderbook_client()
+    symbol_map = asyncio.run(client.get_markets(include_symbol_map=True)).symbol_map or {}
+    if output_format == "raw":
+        raw = {str(index): asset.model_dump() for index, asset in symbol_map.items()}
+        click.echo(json.dumps(raw, indent=2))
+        return
+
+    records = [
+        {
+            "index": index,
+            "symbol": asset.symbol,
+            "name": asset.name,
+            "asset_class": asset.asset_class,
+            "representations": ", ".join(asset.representations),
+        }
+        for index, asset in sorted(symbol_map.items())
+    ]
+    render(records, output_format, no_pager=no_pager)
+
+
 @markets.command("depth")
 @market_data_url_option()
 @ignore_ssl_option()

{tpluspy-0.3.2 → tpluspy-0.5.0}/tplus/_cli/orders.py

@@ -117,7 +117,7 @@ def _replace(
     from tplus.model.asset_identifier import AssetIdentifier
 
     client = cli_ctx.orderbook_client()
-    response = asyncio.run(
+    response, _revision = asyncio.run(
         client.replace_order(
             original_order_id=order_id,
             asset_id=AssetIdentifier(asset_id),

{tpluspy-0.3.2 → tpluspy-0.5.0}/tplus/_cli/settle.py

@@ -78,7 +78,7 @@ def _build_manager(
     vault = cast("DepositVault", DepositVault.at(vault_address)) if vault_address else None
     return SettlementManager(
         default_user=cli_ctx.load_user(),
-        ape_account=signer,
+        account=signer,
         oms_client=cli_ctx.orderbook_client(),
         vault=vault,
     )