Version 0.22.0 (hyperliquid-dex#260)

Add support for general user abstraction actions

Author: traderben

.github/workflows/ci.yml

@@ -33,7 +33,11 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install poetry
-        run: make poetry-download
+        uses: snok/install-poetry@v1
+        with:
+          version: 1.8.5
+          virtualenvs-create: true
+          virtualenvs-in-project: true
 
       - name: Set up cache
         uses: actions/cache@v4
@@ -42,9 +46,7 @@ jobs:
           key: venv-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('poetry.lock') }}
 
       - name: Install dependencies
-        run: |
-          poetry config virtualenvs.in-project true
-          poetry install
+        run: poetry install
 
       - name: Run tests
         run: |

examples/user_abstraction.py

@@ -0,0 +1,47 @@
+import example_utils
+
+from hyperliquid.exchange import Exchange
+from hyperliquid.utils import constants
+
+# set sub-account user address here
+SUB_ACCOUNT_USER = "0x0000000000000000000000000000000000000000"
+
+
+def main():
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
+
+    # set abstraction for user via agent
+    # Note: the account must be in "default" mode to succeed
+    user = exchange.account_address
+    print("current user abstraction state:", info.query_user_abstraction_state(user))
+    agent_set_abstraction_result = exchange.agent_set_abstraction("u")
+    print(agent_set_abstraction_result)
+
+    if user == exchange.wallet.address:
+        # set abstraction for user back to disabled
+        user_set_abstraction_result = exchange.user_set_abstraction(user, "unifiedAccount")
+        print(user_set_abstraction_result)
+        print("current user abstraction state:", info.query_user_abstraction_state(user))
+
+        # set dex abstraction for sub-account of user
+        print("setting abstraction for", SUB_ACCOUNT_USER)
+
+        # set abstraction for user via agent by setting the vault_address to SUB_ACCOUNT_USER
+        exchange_with_sub_account = Exchange(exchange.wallet, exchange.base_url, vault_address=SUB_ACCOUNT_USER)
+        agent_set_abstraction_result = exchange_with_sub_account.agent_set_abstraction("u")
+        print("sub-account agent_set_abstraction result:", agent_set_abstraction_result)
+
+        for abstraction in ["disabled", "portfolioMargin"]:
+            user_set_abstraction_result = exchange.user_set_abstraction(SUB_ACCOUNT_USER, abstraction)
+            print(user_set_abstraction_result)
+            print(
+                "current sub-account user abstraction state:",
+                info.query_user_abstraction_state(SUB_ACCOUNT_USER),
+            )
+
+    else:
+        print("not performing user set abstraction because not user", exchange.account_address, exchange.wallet.address)
+
+
+if __name__ == "__main__":
+    main()

hyperliquid/exchange.py

@@ -31,9 +31,13 @@
     sign_token_delegate_action,
     sign_usd_class_transfer_action,
     sign_usd_transfer_action,
+    sign_user_dex_abstraction_action,
+    sign_user_set_abstraction_action,
     sign_withdraw_from_bridge_action,
 )
 from hyperliquid.utils.types import (
+    Abstraction,
+    AgentAbstraction,
     Any,
     BuilderInfo,
     Cloid,
@@ -1089,67 +1093,37 @@ def multi_sig(self, multi_sig_user, inner_action, signatures, nonce, vault_addre
             signature,
             nonce,
         )
-
-    def enable_user_dex_abstraction(self, enabled: bool) -> Any:
-        """
-        Enable or disable HIP-3 DEX abstraction.
 
-        If set, actions on HIP-3 perps will automatically transfer collateral from 
-        validator-operated USDC perps balance for HIP-3 DEXs where USDC is the collateral token, 
-        and spot otherwise.
-        """
+    def use_big_blocks(self, enable: bool) -> Any:
         timestamp = get_timestamp_ms()
-        is_mainnet = self.base_url == MAINNET_API_URL
-        
-        # Determine Chain IDs and Names based on environment
-        # Mainnet -> Arbitrum One (42161 -> 0xa4b1)
-        # Testnet -> Arbitrum Sepolia (421614 -> 0x66eee)
-        signature_chain_id = "0xa4b1" if is_mainnet else "0x66eee"
-        hyperliquid_chain = "Mainnet" if is_mainnet else "Testnet"
-
-        # Determine the target user address
-        # Priority: Vault Address (Sub-account) > Account Address > Wallet Address
-        user_address = self.wallet.address
-        if self.account_address:
-            user_address = self.account_address
-        if self.vault_address:
-            user_address = self.vault_address
-
         action = {
-            "type": "userDexAbstraction",
-            "hyperliquidChain": hyperliquid_chain,
-            "signatureChainId": signature_chain_id,
-            "user": user_address,
-            "enabled": enabled,
-            "nonce": timestamp,
+            "type": "evmUserModify",
+            "usingBigBlocks": enable,
         }
-
-        # Sign the action
         signature = sign_l1_action(
             self.wallet,
             action,
-            None, 
+            None,
             timestamp,
             self.expires_after,
-            is_mainnet,
+            self.base_url == MAINNET_API_URL,
         )
-
         return self._post_action(
             action,
             signature,
             timestamp,
         )
-        
-    def use_big_blocks(self, enable: bool) -> Any:
+
+    def agent_set_abstraction(self, abstraction: AgentAbstraction) -> Any:
         timestamp = get_timestamp_ms()
         action = {
-            "type": "evmUserModify",
-            "usingBigBlocks": enable,
+            "type": "agentSetAbstraction",
+            "abstraction": abstraction,
         }
         signature = sign_l1_action(
             self.wallet,
             action,
-            None,
+            self.vault_address,
             timestamp,
             self.expires_after,
             self.base_url == MAINNET_API_URL,
@@ -1160,6 +1134,36 @@ def use_big_blocks(self, enable: bool) -> Any:
             timestamp,
         )
 
+    def user_dex_abstraction(self, user: str, enabled: bool) -> Any:
+        timestamp = get_timestamp_ms()
+        action = {
+            "type": "userDexAbstraction",
+            "user": user.lower(),
+            "enabled": enabled,
+            "nonce": timestamp,
+        }
+        signature = sign_user_dex_abstraction_action(self.wallet, action, self.base_url == MAINNET_API_URL)
+        return self._post_action(
+            action,
+            signature,
+            timestamp,
+        )
+
+    def user_set_abstraction(self, user: str, abstraction: Abstraction) -> Any:
+        timestamp = get_timestamp_ms()
+        action = {
+            "type": "userSetAbstraction",
+            "user": user.lower(),
+            "abstraction": abstraction,
+            "nonce": timestamp,
+        }
+        signature = sign_user_set_abstraction_action(self.wallet, action, self.base_url == MAINNET_API_URL)
+        return self._post_action(
+            action,
+            signature,
+            timestamp,
+        )
+
     def noop(self, nonce):
         action = {"type": "noop"}
         signature = sign_l1_action(

hyperliquid/info.py

@@ -632,6 +632,12 @@ def query_user_to_multi_sig_signers(self, multi_sig_user: str) -> Any:
     def query_perp_deploy_auction_status(self) -> Any:
         return self.post("/info", {"type": "perpDeployAuctionStatus"})
 
+    def query_user_dex_abstraction_state(self, user: str) -> Any:
+        return self.post("/info", {"type": "userDexAbstraction", "user": user})
+
+    def query_user_abstraction_state(self, user: str) -> Any:
+        return self.post("/info", {"type": "userAbstraction", "user": user})
+
     def historical_orders(self, user: str) -> Any:
         """Retrieve a user's historical orders.
 

hyperliquid/utils/signing.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 import time
 from decimal import Decimal
 
@@ -115,6 +117,20 @@
     {"name": "nonce", "type": "uint64"},
 ]
 
+USER_DEX_ABSTRACTION_SIGN_TYPES = [
+    {"name": "hyperliquidChain", "type": "string"},
+    {"name": "user", "type": "address"},
+    {"name": "enabled", "type": "bool"},
+    {"name": "nonce", "type": "uint64"},
+]
+
+USER_SET_ABSTRACTION_SIGN_TYPES = [
+    {"name": "hyperliquidChain", "type": "string"},
+    {"name": "user", "type": "address"},
+    {"name": "abstraction", "type": "string"},
+    {"name": "nonce", "type": "uint64"},
+]
+
 TOKEN_DELEGATE_TYPES = [
     {"name": "hyperliquidChain", "type": "string"},
     {"name": "validator", "type": "address"},
@@ -362,6 +378,26 @@ def sign_send_asset_action(wallet, action, is_mainnet):
     )
 
 
+def sign_user_dex_abstraction_action(wallet, action, is_mainnet):
+    return sign_user_signed_action(
+        wallet,
+        action,
+        USER_DEX_ABSTRACTION_SIGN_TYPES,
+        "HyperliquidTransaction:UserDexAbstraction",
+        is_mainnet,
+    )
+
+
+def sign_user_set_abstraction_action(wallet, action, is_mainnet):
+    return sign_user_signed_action(
+        wallet,
+        action,
+        USER_SET_ABSTRACTION_SIGN_TYPES,
+        "HyperliquidTransaction:UserSetAbstraction",
+        is_mainnet,
+    )
+
+
 def sign_convert_to_multi_sig_user_action(wallet, action, is_mainnet):
     return sign_user_signed_action(
         wallet,
@@ -479,11 +515,11 @@ def order_request_to_order_wire(order: OrderRequest, asset: int) -> OrderWire:
     return order_wire
 
 
-def order_wires_to_order_action(order_wires, builder=None):
+def order_wires_to_order_action(order_wires: list[OrderWire], builder: Any = None, grouping: Grouping = "na") -> Any:
     action = {
         "type": "order",
         "orders": order_wires,
-        "grouping": "na",
+        "grouping": grouping,
     }
     if builder:
         action["builder"] = builder

hyperliquid/utils/types.py

@@ -183,6 +183,8 @@
 
 # b is the public address of the builder, f is the amount of the fee in tenths of basis points. e.g. 10 means 1 basis point
 BuilderInfo = TypedDict("BuilderInfo", {"b": str, "f": int})
+Abstraction = Literal["unifiedAccount", "portfolioMargin", "disabled"]
+AgentAbstraction = Literal["u", "p", "i"]
 
 PerpDexSchemaInput = TypedDict(
     "PerpDexSchemaInput", {"fullName": str, "collateralToken": int, "oracleUpdater": Optional[str]}

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "hyperliquid-python-sdk"
-version = "0.19.0"
+version = "0.22.0"
 description = "SDK for Hyperliquid API trading with Python."
 readme = "README.md"
 authors = ["Hyperliquid <hello@hyperliquid.xyz>"]