Version 0.13.0

Author: traderben

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/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()