feat: ✨ Integrate VerificationPayloads

README.md

@@ -183,17 +183,9 @@ All operations correspond to CoreWriter precompile actions:
 | Method | Action ID | Description |
 |--------|-----------|-------------|
 | `limit_order` | 1 | Place a limit order |
-| `vault_transfer` | 2 | Transfer to/from vault |
-| `token_delegate` | 3 | Delegate/undelegate tokens |
-| `staking_deposit` | 4 | Deposit for staking |
-| `staking_withdraw` | 5 | Withdraw from staking |
-| `spot_send` | 6 | Send spot tokens |
-| `perp_send` | 7 | Send perp collateral |
-| `usd_class_transfer_to_perp` | 8 | Transfer USD to perp |
-| `usd_class_transfer_to_spot` | 9 | Transfer USD to spot |
-| `cancel_order` | 10 | Cancel order by cloid |
-| `finalize_subaccount` | 11 | Finalize subaccount |
-| `approve_builder_fee` | 12 | Approve builder fee |
+| `spot_send` | 6 | Transfer tokens from Core to EVM |
+| `usd_class_transfer_to_perp/spot` | 7 | Transfer USD to/from perp |
+| `cancel_order` | 10/11 | Cancel order by cloid or oid |
 
 ## Integration
 

examples/05_evm_usd_class_transfers.py

@@ -63,6 +63,7 @@ def main() -> None:
         mn_rpc_url=mn_rpc_url,
         hl_strategy_address=hl_strategy_address,
         bridge_strategy_address=bridge_address,
+        disable_call_verification=True,  # Skip call verification for this example
     )
 
     logging.info("Connecting to HyperLiquid EVM at %s", hl_rpc_url)

examples/06_evm_place_and_cancel_order.py

@@ -43,6 +43,7 @@ def main() -> None:
         mn_rpc_url=mn_rpc_url,
         hl_strategy_address=strategy_address,
         bridge_strategy_address=bridge_address,
+        disable_call_verification=True,  # Skip call verification for this example
     )
 
     hl.connect()

examples/07_evm_market_orders.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import json
 import logging
 import os
 import time
 from decimal import Decimal
+from pathlib import Path
 
 from dotenv import load_dotenv
 
@@ -39,12 +41,17 @@ def main() -> None:
     if not bridge_address:
         raise ValueError("BRIDGE_STRATEGY not found in environment variables")
 
+    proof_blob_path = Path(__file__).with_name("example_verification_blob.json")
+    with proof_blob_path.open("r", encoding="utf-8") as proof_file:
+        verification_blob = json.load(proof_file)
+
     client = HLProtocolEVM(
         private_key=private_key,
         hl_rpc_url=hl_rpc_url,
         mn_rpc_url=mn_rpc_url,
         hl_strategy_address=hl_strategy_address,
         bridge_strategy_address=bridge_address,
+        flexible_vault_proof_blob=verification_blob,
     )
 
     client.connect()

examples/08_evm_cctp_roundtrip.py

@@ -4,12 +4,14 @@
 
 import logging
 import os
+from pathlib import Path
 from typing import Any
+import json
 
 from dotenv import load_dotenv
 
 from hl_api import HLProtocolEVM
-from hl_api.types import BridgeResponse
+from hl_api.types import Response
 
 load_dotenv()
 
@@ -30,7 +32,7 @@ def _require_env(name: str) -> str:
     return value
 
 
-def _log_bridge_result(label: str, response: BridgeResponse) -> None:
+def _log_bridge_result(label: str, response: Response) -> None:
     context: dict[str, Any] = response.raw_response or {}
     if response.success:
         logger.info("%s succeeded (amount %.6f USDC)", label, response.amount or 0.0)
@@ -57,13 +59,18 @@ def main() -> None:
 
     amount = float(os.getenv("BRIDGE_AMOUNT_USDC", str(DEFAULT_AMOUNT)))
 
+    proof_blob_path = Path(__file__).with_name("example_verification_blob.json")
+    with proof_blob_path.open("r", encoding="utf-8") as proof_file:
+        verification_blob = json.load(proof_file)
+
     client = HLProtocolEVM(
         private_key=private_key,
         hl_rpc_url=hl_rpc_url,
         mn_rpc_url=mn_rpc_url,
         hl_strategy_address=hl_strategy_address,
         bridge_strategy_address=bridge_strategy_address,
         testnet=testnet,
+        flexible_vault_proof_blob=verification_blob,
     )
 
     client.connect()

examples/example_verification_blob.json

@@ -0,0 +1,76 @@
+{
+  "title": "hyperevm:tqETH:subvault0",
+  "merkle_root": "0x8cacec5a1f3021c50d6e4f4ac80121df88f6fb6f636f981bcbd169eefaed3da3",
+  "merkle_proofs": [
+    {
+      "verificationType": 3,
+      "description": "CoreWriter.sendRawAction{action: limit_order}(anyBytes)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    },
+    {
+      "verificationType": 3,
+      "description": "CoreWriter.sendRawAction{action: cancel_oid}(anyBytes)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    },
+     {
+      "verificationType": 3,
+      "description": "CoreWriter.sendRawAction{action: cancel_cloid}(anyBytes)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    },
+     {
+      "verificationType": 3,
+      "description": "CoreWriter.sendRawAction{action: spot_send}(anyBytes)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    },
+    {
+      "verificationType": 3,
+      "description": "CoreWriter.sendRawAction{action: usd_transfer}(anyBytes)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    },
+    {
+      "verificationType": 3,
+      "description": "USDC.approve(TokenMessenger, anyInt)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    },
+     {
+      "verificationType": 3,
+      "description": "TokenMessenger.depositForBurn(anyInt)",
+      "verificationData": "0x0000000000000000000000000000000263fb29c3d6b0c5837883519ef05ea20a04d1b33472333c382f6830bd3e61bf513e62ad79b5f3441f8ff182fb929fcae000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000000000000000000000000000000000000000000000000000000000000000ffffffff00000000000000000000000000000000000000000000000000000000",
+      "proof": [
+        "0x309b822df17cf8c5bc2494ec60d9d2b59a75b6b698a6c86a51fcf37a7f7da974",
+        "0x4ca29eeb08d7c9b554ee3baff79abf1060d56c2fbcd2eb4f879018b4c6737ebf",
+        "0x3c1feb2292bf6df1ecbcd268a9bdb51445d095acfdf61e0a397870deeed573a8"
+      ]
+    }
+  ]
+}

src/hl_api/__init__.py

@@ -10,43 +10,28 @@
 from .exceptions import (
     AuthenticationError,
     HLProtocolError,
+    MethodNotImplementedError,
     NetworkError,
-    NotImplementedError,
-    OrderError,
-    TransferError,
     ValidationError,
 )
 from .types import (
     TIF,
-    # Enums
     ActionID,
     Address,
-    ApprovalResponse,
-    BridgeResponse,
-    CancelResponse,
-    DelegateResponse,
-    FinalizeResponse,
-    # Response types
-    OrderResponse,
-    # Type aliases
+    BridgeDirection,
     Price,
-    SendResponse,
+    Response,
     Size,
-    StakingResponse,
-    TransferResponse,
-    WalletResponse,
+    VerificationPayload,
     Wei,
 )
 from .utils import (
     cloid_to_uint128,
     decode_tif,
     encode_tif,
+    from_uint64,
     generate_cloid,
-    price_to_uint64,
-    size_to_uint64,
-    uint64_to_price,
-    uint64_to_size,
-    validate_address,
+    to_uint64,
 )
 
 __version__ = "0.1.0"
@@ -59,36 +44,24 @@
     # Types and enums
     "ActionID",
     "TIF",
-    "OrderResponse",
-    "CancelResponse",
-    "TransferResponse",
-    "DelegateResponse",
-    "StakingResponse",
-    "SendResponse",
-    "FinalizeResponse",
-    "WalletResponse",
-    "ApprovalResponse",
-    "BridgeResponse",
+    "BridgeDirection",
+    "Response",
+    "VerificationPayload",
     "Price",
     "Size",
     "Address",
     "Wei",
     # Exceptions
     "HLProtocolError",
     "AuthenticationError",
-    "OrderError",
-    "TransferError",
     "NetworkError",
     "ValidationError",
-    "NotImplementedError",
+    "MethodNotImplementedError",
     # Utility functions
-    "price_to_uint64",
-    "uint64_to_price",
-    "size_to_uint64",
-    "uint64_to_size",
+    "to_uint64",
+    "from_uint64",
     "encode_tif",
     "decode_tif",
     "generate_cloid",
-    "validate_address",
     "cloid_to_uint128",
 ]