Merge branch 'master' into master

Author: BriungRi

examples/basic_order_with_builder_deployed_dex.py

@@ -0,0 +1,53 @@
+# This example shows how to place and query orders for a builder-deployed perp dex
+import json
+
+import example_utils
+
+from hyperliquid.utils import constants
+
+DUMMY_DEX = "test"
+COIN = f"{DUMMY_DEX}:ABC"
+
+
+def main():
+    # Supply the builder-deployed perps dex as an argument
+    address, info, exchange = example_utils.setup(
+        base_url=constants.TESTNET_API_URL, skip_ws=True, perp_dexs=[DUMMY_DEX]
+    )
+
+    # Get the user state and print out position information
+    user_state = info.user_state(address)
+    positions = []
+    for position in user_state["assetPositions"]:
+        positions.append(position["position"])
+    if len(positions) > 0:
+        print("positions:")
+        for position in positions:
+            print(json.dumps(position, indent=2))
+    else:
+        print("no open positions")
+
+    # Print the meta for DUMMY_DEX
+    print("dummy dex meta:", info.meta(dex=DUMMY_DEX))
+
+    # Place an order that should rest by setting the price very low
+    order_result = exchange.order(COIN, True, 20, 1, {"limit": {"tif": "Gtc"}})
+    print(order_result)
+
+    # Query the order status by oid
+    if order_result["status"] == "ok":
+        status = order_result["response"]["data"]["statuses"][0]
+        if "resting" in status:
+            order_status = info.query_order_by_oid(address, status["resting"]["oid"])
+            print("Order status by oid:", order_status)
+
+    # Cancel the order
+    if order_result["status"] == "ok":
+        status = order_result["response"]["data"]["statuses"][0]
+        if "resting" in status:
+            cancel_result = exchange.cancel(COIN, status["resting"]["oid"])
+            print(cancel_result)
+
+
+if __name__ == "__main__":
+    main()

examples/basic_recover_user.py

@@ -0,0 +1,59 @@
+from hyperliquid.utils.signing import (
+    TOKEN_DELEGATE_TYPES,
+    recover_agent_or_user_from_l1_action,
+    recover_user_from_user_signed_action,
+)
+
+
+def main():
+    example_l1_signed_action = {
+        "signature": {
+            "r": "0xd088ceb979ab7616f21fd7dabee04342235bd3af6d82a6d153b503c34c73bc93",
+            "s": "0x425d8467a69f4d0ff6d9ddfb360ef6152c8165cdd20329e03b0a8f19890d73e",
+            "v": 27,
+        },
+        "vaultAddress": "0xc64cc00b46101bd40aa1c3121195e85c0b0918d8",
+        "action": {"type": "cancel", "cancels": [{"a": 87, "o": 28800768235}]},
+        "nonce": 1745532560074,
+    }
+    agent_or_user = recover_agent_or_user_from_l1_action(
+        example_l1_signed_action["action"],
+        example_l1_signed_action["signature"],
+        example_l1_signed_action["vaultAddress"],
+        example_l1_signed_action["nonce"],
+        None,
+        False,
+    )
+    print("recovered l1 action agent or user:", agent_or_user)
+
+    example_user_signed_action = {
+        "signature": {
+            "r": "0xa00406eb38821b8918743fab856c103132261e8d990852a8ee25e6f2e88891b",
+            "s": "0x34cf47cfbf09173bcb851bcfdce3ad83dd64ed791ab32bfe9606d25e7c608859",
+            "v": 27,
+        },
+        "action": {
+            "type": "tokenDelegate",
+            "signatureChainId": "0xa4b1",
+            "hyperliquidChain": "Mainnet",
+            "validator": "0x5ac99df645f3414876c816caa18b2d234024b487",
+            "wei": 100163871320,
+            "isUndelegate": True,
+            "nonce": 1744932112279,
+        },
+        "isFrontend": True,
+        "nonce": 1744932112279,
+    }
+
+    user = recover_user_from_user_signed_action(
+        example_user_signed_action["action"],
+        example_user_signed_action["signature"],
+        TOKEN_DELEGATE_TYPES,
+        "HyperliquidTransaction:TokenDelegate",
+        True,
+    )
+    print("recovered user-signed action user:", user)
+
+
+if __name__ == "__main__":
+    main()

examples/c_signer.py

@@ -0,0 +1,28 @@
+# Example script to run CSigner actions
+# See https://github.com/hyperliquid-dex/node?tab=readme-ov-file#begin-validating for spec
+#
+# IMPORTANT: Replace any arguments for the exchange calls below to match your deployment requirements.
+
+import example_utils
+
+from hyperliquid.utils import constants
+
+# Change to one of "Jail" or "Unjail"
+ACTION = ""
+
+
+def main():
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
+
+    if ACTION == "Jail":
+        jail_result = exchange.c_signer_jail_self()
+        print("jail result", jail_result)
+    elif ACTION == "Unjail":
+        unjail_result = exchange.c_signer_unjail_self()
+        print("unjail result", unjail_result)
+    else:
+        raise ValueError("Invalid action specified")
+
+
+if __name__ == "__main__":
+    main()

examples/c_validator.py

@@ -0,0 +1,64 @@
+# Example script to register a validator
+# See https://github.com/hyperliquid-dex/node?tab=readme-ov-file#join-network for spec
+#
+# IMPORTANT: Replace any arguments for the exchange calls below to match your deployment requirements.
+
+import example_utils
+
+from hyperliquid.utils import constants
+
+# Change to one of "Register", "ChangeProfile", or "Unregister"
+ACTION = ""
+DUMMY_SIGNER = "0x0000000000000000000000000000000000000001"
+
+
+def main():
+    address, info, exchange = example_utils.setup(constants.TESTNET_API_URL, skip_ws=True)
+
+    if ACTION == "Register":
+        node_ip = "1.2.3.4"
+        name = "..."
+        description = "..."
+        delegations_disabled = True
+        commission_bps = 5
+        signer = DUMMY_SIGNER
+        unjailed = False
+        initial_wei = 100000
+        register_result = exchange.c_validator_register(
+            node_ip,
+            name,
+            description,
+            delegations_disabled,
+            commission_bps,
+            signer,
+            unjailed,
+            initial_wei,
+        )
+        print("register result", register_result)
+    elif ACTION == "ChangeProfile":
+        node_ip = None
+        name = None
+        description = None
+        unjailed = False
+        disable_delegations = None
+        commission_bps = None
+        signer = None
+        change_profile_result = exchange.c_validator_change_profile(
+            node_ip,
+            name,
+            description,
+            unjailed,
+            disable_delegations,
+            commission_bps,
+            signer,
+        )
+        print("change profile result", change_profile_result)
+    elif ACTION == "Unregister":
+        unregister_result = exchange.c_validator_unregister()
+        print("unregister result", unregister_result)
+    else:
+        raise ValueError("Invalid action specified")
+
+
+if __name__ == "__main__":
+    main()

examples/evm_erc20.py

@@ -278,7 +278,7 @@ class FinalizeEvmContractAction(TypedDict):
         },
     }
     nonce = get_timestamp_ms()
-    signature = sign_l1_action(account, action, None, nonce, False)
+    signature = sign_l1_action(account, action, None, nonce, None, False)
     payload = {
         "action": action,
         "nonce": nonce,
@@ -299,7 +299,7 @@ class FinalizeEvmContractAction(TypedDict):
     else:
         finalize_action = {"type": "finalizeEvmContract", "token": TOKEN, "input": "firstStorageSlot"}
     nonce = get_timestamp_ms()
-    signature = sign_l1_action(account, finalize_action, None, nonce, False)
+    signature = sign_l1_action(account, finalize_action, None, nonce, None, False)
     payload = {
         "action": finalize_action,
         "nonce": nonce,

examples/example_utils.py

@@ -8,7 +8,7 @@
 from hyperliquid.info import Info
 
 
-def setup(base_url=None, skip_ws=False):
+def setup(base_url=None, skip_ws=False, perp_dexs=None):
     config_path = os.path.join(os.path.dirname(__file__), "config.json")
     with open(config_path) as f:
         config = json.load(f)
@@ -19,7 +19,7 @@ def setup(base_url=None, skip_ws=False):
     print("Running with account address:", address)
     if address != account.address:
         print("Running with agent address:", account.address)
-    info = Info(base_url, skip_ws)
+    info = Info(base_url, skip_ws, perp_dexs=perp_dexs)
     user_state = info.user_state(address)
     spot_user_state = info.spot_user_state(address)
     margin_summary = user_state["marginSummary"]
@@ -28,7 +28,7 @@ def setup(base_url=None, skip_ws=False):
         url = info.base_url.split(".", 1)[1]
         error_string = f"No accountValue:\nIf you think this is a mistake, make sure that {address} has a balance on {url}.\nIf address shown is your API wallet address, update the config to specify the address of your account, not the address of the API wallet."
         raise Exception(error_string)
-    exchange = Exchange(account, base_url, account_address=address)
+    exchange = Exchange(account, base_url, account_address=address, perp_dexs=perp_dexs)
     return address, info, exchange
 
 

examples/multi_sig_order.py

@@ -38,6 +38,7 @@ def main():
             timestamp,
             multi_sig_user,
             address,
+            exchange.expires_after,
         )
         signatures.append(signature)
 

examples/multi_sig_register_token.py

@@ -41,6 +41,7 @@ def main():
             timestamp,
             multi_sig_user,
             address,
+            exchange.expires_after,
         )
         signatures.append(signature)
 

examples/parse_token_delegate_from_replica_cmds.py

@@ -0,0 +1,83 @@
+import argparse
+import json
+import os
+from collections import defaultdict
+
+import lz4.frame
+
+from hyperliquid.utils.signing import TOKEN_DELEGATE_TYPES, recover_user_from_user_signed_action
+
+REPLICA_CMD_BATCH_SIZE = 10000
+
+
+def decompress_lz4(input_file, output_file):
+    with open(input_file, "rb") as f_in:
+        compressed_data = f_in.read()
+
+    decompressed_data = lz4.frame.decompress(compressed_data)
+
+    with open(output_file, "wb") as f_out:
+        f_out.write(decompressed_data)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="parse token delegate actions from replica cmds")
+    parser.add_argument("--data-dir", type=str, required=True)
+    parser.add_argument("--start-height", type=int, required=True)
+    parser.add_argument("--end-height", type=int, required=True)
+    args = parser.parse_args()
+
+    data_dir = args.data_dir
+    start_height = args.start_height
+    end_height = args.end_height
+
+    if start_height % REPLICA_CMD_BATCH_SIZE == 0:
+        raise Exception("start height is not aligned with replica cmd batch size")
+    if end_height % REPLICA_CMD_BATCH_SIZE == 0:
+        raise Exception("end height is not aligned with replica cmd batch size")
+
+    flns = []
+    for height in range(start_height, end_height, REPLICA_CMD_BATCH_SIZE):
+        lz4_fln = f"{data_dir}/{height}.lz4"
+        if not os.path.exists(lz4_fln):
+            raise Exception(
+                f"replica cmds file at {height} not found - download missing block files(s) using 'aws s3 cp s3://hl-[testnet | mainnet]-replica-cmds/<block_object_path> --request-payer requester'"
+            )
+        fln = f"{data_dir}/{height}"
+        decompress_lz4(lz4_fln, fln)
+        flns.append(fln)
+
+    user_to_validator_to_amount: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+
+    for fln in flns:
+        f = open(fln)
+        lines = f.readlines()
+        for line in lines:
+            if "tokenDelegate" not in line:
+                continue
+            data = json.loads(line)
+            bundles = data["abci_block"]["signed_action_bundles"]
+            for bundle in bundles:
+                for signed_action in bundle[1]["signed_actions"]:
+                    action = signed_action["action"]
+                    if action["type"] != "tokenDelegate":
+                        continue
+                    validator = action["validator"]
+                    wei = action["wei"]
+                    is_delegate = not action["isUndelegate"]
+                    user = recover_user_from_user_signed_action(
+                        action,
+                        signed_action["signature"],
+                        TOKEN_DELEGATE_TYPES,
+                        "HyperliquidTransaction:TokenDelegate",
+                        True,
+                    )
+                    if not is_delegate:
+                        wei = -wei
+                    user_to_validator_to_amount[user][validator] += wei / 100_000_000  # native token wei decimals
+
+    print("user to validator to wei amount delegated", user_to_validator_to_amount)
+
+
+if __name__ == "__main__":
+    main()