hyperliquid 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7969eed04a0b822b7be2c29c3ab57f97f077eaf8ed245bc48cb4916fd6b5836
-  data.tar.gz: d37e1acbf31a1e26454071ede7c83fcccf842bf9524835def63a652e77fff1af
+  metadata.gz: 3bf3db383f0da2f70b1d7e98e8901f29fbb4cde940a18859c57c98592c4ffbf3
+  data.tar.gz: 0055af5f445d241193e27189a585423e3410d296a7df96ba447827299a9b9cd4
 SHA512:
-  metadata.gz: 1a7bc66c9acd82975bb1e5929d2f4b77469c5e52b3c9824f7ce5306ad642c1e065531d6f4c20134cdab85c350b2f694736c5a414ee6e7a564d35abc658ed1074
-  data.tar.gz: 9898cba2cbf564dff73f950a29423dd5f42ab2fddf62458418d365546893dabdc5f3ddf159f1af31c7e6254ff02aeaa1a77ca0c63f6198931ee291319daaab82
+  metadata.gz: 32986974696870940a6ca517f963be23faf84c3dfc7adbfe14f0bcfb5d919118c683ab7f3faa9fd3cfa3249c95c92d89f240cc15917e3e18092331e6141a59de
+  data.tar.gz: 9a2d495448ba88243b14bfae7f0fe81ddebab3dbc743dce21742b58955196ff9cdd7a6e6a45cea2d958e00cd023748250c923d203258e32d346390638dd4e9de

data/.rubocop.yml

@@ -26,10 +26,11 @@ Metrics/BlockLength:
     - 'spec/**/*'
     - '*.gemspec'
 
-# Exchange API methods require many parameters
+# Exchange API methods (and multi-sig co-signer helpers that pass through to them) require many parameters
 Metrics/ParameterLists:
   Exclude:
     - 'lib/hyperliquid/exchange.rb'
+    - 'lib/hyperliquid/signing/multi_sig.rb'
 
 # Allow higher complexity for order type conversion logic and WS message handling
 Metrics/CyclomaticComplexity:

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.5.0] - 2026-05-08
+
+### New Exchange actions
+
+- `Exchange#multi_sig(multi_sig_user:, inner_action:, signatures:, nonce:, vault_address:)` — wraps any inner action with N pre-collected co-signer signatures and submits via the user-signed multi-sig envelope. Adds `MULTI_SIG_TYPES` (first EIP-712 type using `bytes32`).
+- `Exchange#create_vault(name:, description:, initial_usd:, ...)` — L1 action that creates a new vault with the calling wallet as leader. Float-USD scaled to integer micro-USD via `float_to_usd_int`.
+
+### New signing primitives
+
+- `Signing::MultiSig` module with `build_envelope`, `envelope_action_hash`, `sign_as_co_signer_l1` (for L1 inner actions, phantom-agent flow), and `sign_as_co_signer_user_signed` (enriches the inner action's typed-data spec with `payloadMultiSigUser` + `outerSigner` fields). Co-signature collection remains the caller's responsibility.
+- `Signer.compute_action_hash` exposed as a public class method (refactored out of `construct_phantom_agent` for reuse from multi-sig).
+
+### Tests
+
+- Fixture-based byte-parity specs against Python `eth_account` 0.13.7 + `msgpack` 1.1.2 covering: outer multi-sig signature with no co-signers, outer + L1 co-signer signatures over an order action, and a user-signed co-signer signature over a sendAsset action.
+
 ## [1.4.0] - 2026-05-05
 
 ### New Exchange actions

data/CLAUDE.md

@@ -65,6 +65,8 @@ Any change to signing must maintain parity with the Python SDK or transactions w
 
 User-signed actions (`usd_send`, `withdraw_from_bridge`, `send_to_evm_with_data`, etc.) use direct EIP-712 typed-data signing with the `HyperliquidSignTransaction` domain (chain ID 421614) — not the phantom-agent flow. Each has a typed-data spec in `Signing::EIP712`. The `eth` gem's typed-data signer handles primitive types (`string`, `uint*`, `address`, `bool`) and dynamic `bytes` correctly — `send_to_evm_with_data` was the first to use `bytes`, and its spec includes a fixture-based signature parity test against `eth_account` to lock that in. When adding new user-signed actions with non-string types, add a similar fixture to catch eth-gem regressions.
 
+Multi-sig actions (`Exchange#multi_sig`) wrap any inner action with N co-signer signatures. The submitter's outer signature uses `MULTI_SIG_TYPES` over `{hyperliquidChain, multiSigActionHash, nonce}`; the `multiSigActionHash` is `Signer.compute_action_hash` of the multi-sig envelope (with `:type` stripped). Co-signer signing is exposed via `Signing::MultiSig.sign_as_co_signer_l1` (for L1 inner actions — signs `[multi_sig_user, outer_signer, action]` via phantom-agent) and `Signing::MultiSig.sign_as_co_signer_user_signed` (enriches the inner action's typed-data spec with `payloadMultiSigUser`+`outerSigner` address fields). Both mirror the Python SDK byte-for-byte; specs include fixture-based parity tests captured against `eth_account`+`msgpack`. Co-signature *collection* is the caller's responsibility — the SDK does not coordinate signing rooms.
+
 ### Numeric Conversion
 
 - **`float_to_wire`** (in Exchange): converts to string with 8-decimal precision, validates rounding tolerance (`1e-12`), normalizes trailing zeros. No scientific notation.

data/lib/hyperliquid/exchange.rb

@@ -793,6 +793,40 @@ module Hyperliquid
       post_action(action, signature, nonce, nil)
     end
 
+    # Submit a multi-signature action wrapping any inner exchange action with N pre-collected
+    # co-signer signatures (`multiSig` user-signed envelope). The submitter's outer signature
+    # authorises execution; co-signer signatures must be collected externally via
+    # `Signing::MultiSig.sign_as_co_signer_l1` (for L1 inner actions) or
+    # `Signing::MultiSig.sign_as_co_signer_user_signed` (for user-signed inner actions).
+    # @param multi_sig_user [String] Address of the multi-sig user being acted on
+    # @param inner_action [Hash] The wrapped action body
+    # @param signatures [Array<Hash>] Co-signer signatures (each :r, :s, :v)
+    # @param nonce [Integer, nil] Nonce timestamp; defaults to `timestamp_ms`. Must match the
+    #   nonce used by every co-signer when they signed.
+    # @param vault_address [String, nil] Optional vault address (must match co-signer hashes)
+    # @return [Hash] Exchange response
+    def multi_sig(multi_sig_user:, inner_action:, signatures:, nonce: nil, vault_address: nil)
+      nonce ||= timestamp_ms
+      envelope = Signing::MultiSig.build_envelope(
+        inner_action: inner_action,
+        multi_sig_user: multi_sig_user,
+        outer_signer: @signer.address,
+        signatures: signatures
+      )
+      multi_sig_action_hash = Signing::MultiSig.envelope_action_hash(
+        envelope: envelope,
+        nonce: nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      signature = @signer.sign_user_signed_action(
+        { multiSigActionHash: multi_sig_action_hash, nonce: nonce },
+        Signing::MultiSig::OUTER_PRIMARY_TYPE,
+        Signing::EIP712::MULTI_SIG_TYPES
+      )
+      post_action(envelope, signature, nonce, vault_address)
+    end
+
     # Claim accrued referral-program rewards (`claimRewards` L1 action).
     # @return [Hash] Exchange response
     def claim_rewards
@@ -893,6 +927,29 @@ module Hyperliquid
       post_action(action, signature, nonce, nil)
     end
 
+    # Create a new vault with the calling wallet as leader (`createVault` L1 action).
+    # @param name [String] Vault name (server-enforced 3–50 characters)
+    # @param description [String] Vault description (server-enforced 10–250 characters)
+    # @param initial_usd [Numeric] Initial USD seed (server-enforced $100 minimum);
+    #   scaled internally to integer 1e6 micro-USD
+
+    # @return [Hash] Exchange response — on success `response.data` is the new vault address
+    def create_vault(name:, description:, initial_usd:)
+      nonce = timestamp_ms
+      action = {
+        type: 'createVault',
+        name: name,
+        description: description,
+        initialUsd: float_to_usd_int(initial_usd),
+        nonce: nonce
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
     # Borrow, lend, supply, or withdraw HIP-2 borrow/lend assets (`borrowLend` L1 action).
     # Companion to the four HIP-2 info methods (`borrow_lend_user_state` etc.).
     # @param operation [String] One of 'supply', 'withdraw', 'repay', 'borrow'

data/lib/hyperliquid/signing/eip712.rb

@@ -130,6 +130,14 @@ module Hyperliquid
         ]
       }.freeze
 
+      MULTI_SIG_TYPES = {
+        'HyperliquidTransaction:SendMultiSig': [
+          { name: :hyperliquidChain,   type: 'string'  },
+          { name: :multiSigActionHash, type: 'bytes32' },
+          { name: :nonce,              type: 'uint64'  }
+        ]
+      }.freeze
+
       SEND_TO_EVM_WITH_DATA_TYPES = {
         'HyperliquidTransaction:SendToEvmWithData': [
           { name: :hyperliquidChain,     type: 'string' },

data/lib/hyperliquid/signing/multi_sig.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'msgpack'
+
+module Hyperliquid
+  module Signing
+    # Multi-signature action helpers — submitter envelope construction and co-signer signing.
+    #
+    # Mirrors the official Python SDK's three multi-sig flows:
+    #   1. `Exchange#multi_sig` (the submitter — signs the outer envelope)
+    #   2. `sign_as_co_signer_l1`        — co-signer for L1 inner actions (orders, cancels, etc.)
+    #   3. `sign_as_co_signer_user_signed` — co-signer for user-signed inner actions
+    #                                       (sendAsset, usdSend, etc.)
+    #
+    # Co-signature collection is the caller's responsibility — these helpers produce a single
+    # co-signer signature; the submitter then assembles the array and posts the envelope.
+    module MultiSig
+      OUTER_PRIMARY_TYPE = 'HyperliquidTransaction:SendMultiSig'
+
+      # Build the outer multi-sig envelope (the action body posted to /exchange).
+      # @param inner_action [Hash] The wrapped action (any L1 or user-signed action body)
+      # @param multi_sig_user [String] Address of the multi-sig user (lowercased)
+      # @param outer_signer [String] Address of the submitter (lowercased)
+      # @param signatures [Array<Hash>] Pre-collected co-signer signatures
+      # @return [Hash] Multi-sig envelope ready for signing + posting
+      def self.build_envelope(inner_action:, multi_sig_user:, outer_signer:, signatures:)
+        {
+          type: 'multiSig',
+          signatureChainId: '0x66eee',
+          signatures: signatures,
+          payload: {
+            multiSigUser: multi_sig_user.downcase,
+            outerSigner: outer_signer.downcase,
+            action: inner_action
+          }
+        }
+      end
+
+      # Compute the multiSigActionHash that the submitter signs over.
+      # Mirrors Python's `sign_multi_sig_action`: action_hash(envelope - type, vault, nonce, expires).
+      # @param envelope [Hash] The multi-sig envelope (will have :type stripped before hashing)
+      # @param nonce [Integer] Nonce timestamp (ms)
+      # @param vault_address [String, nil] Optional vault address
+      # @param expires_after [Integer, nil] Optional expiration timestamp (ms)
+      # @return [String] 0x-prefixed 32-byte hex hash
+      def self.envelope_action_hash(envelope:, nonce:, vault_address: nil, expires_after: nil)
+        without_type = envelope.dup
+        without_type.delete(:type)
+        Signer.compute_action_hash(without_type, nonce, vault_address: vault_address,
+                                                        expires_after: expires_after)
+      end
+
+      # Co-signer flow for L1 inner actions (orders, cancels, leverage, etc.).
+      # The signed payload is the list `[multi_sig_user, outer_signer, action]`, hashed and
+      # signed via the L1 phantom-agent flow.
+      #
+      # @param signer [Signer] Co-signer's wallet
+      # @param inner_action [Hash] The wrapped L1 action
+      # @param multi_sig_user [String] Multi-sig user address
+      # @param outer_signer [String] Submitter address (NOT the co-signer's address)
+      # @param nonce [Integer] Nonce timestamp (ms)
+      # @param vault_address [String, nil] Optional vault address
+      # @param expires_after [Integer, nil] Optional expiration timestamp (ms)
+      # @return [Hash] Signature with :r, :s, :v
+      def self.sign_as_co_signer_l1(signer:, inner_action:, multi_sig_user:, outer_signer:, nonce:,
+                                    vault_address: nil, expires_after: nil)
+        envelope = [multi_sig_user.downcase, outer_signer.downcase, inner_action]
+        signer.sign_l1_action(envelope, nonce, vault_address: vault_address,
+                                               expires_after: expires_after)
+      end
+
+      # Co-signer flow for user-signed inner actions (sendAsset, usdSend, etc.).
+      # Enriches the inner action with `payloadMultiSigUser` + `outerSigner` fields and the
+      # corresponding type entries, then signs via the user-signed typed-data flow.
+      #
+      # @param signer [Signer] Co-signer's wallet
+      # @param inner_action [Hash] The wrapped user-signed action body
+      # @param multi_sig_user [String] Multi-sig user address
+      # @param outer_signer [String] Submitter address
+      # @param primary_type [String] Inner action's EIP-712 primary type (e.g. 'HyperliquidTransaction:SendAsset')
+      # @param sign_types [Hash] Inner action's EIP-712 type definitions
+      # @return [Hash] Signature with :r, :s, :v
+      def self.sign_as_co_signer_user_signed(signer:, inner_action:, multi_sig_user:, outer_signer:,
+                                             primary_type:, sign_types:)
+        enriched_action = inner_action.merge(
+          payloadMultiSigUser: multi_sig_user.downcase,
+          outerSigner: outer_signer.downcase
+        )
+        enriched_types = enrich_user_signed_types(sign_types)
+        signer.sign_user_signed_action(enriched_action, primary_type, enriched_types)
+      end
+
+      # Insert payloadMultiSigUser + outerSigner type entries immediately after hyperliquidChain.
+      # Matches Python SDK's `add_multi_sig_types`.
+      def self.enrich_user_signed_types(sign_types)
+        sign_types.each_with_object({}) do |(key, fields), result|
+          new_fields = []
+          fields.each do |f|
+            new_fields << f
+            if f[:name].to_s == 'hyperliquidChain'
+              new_fields << { name: :payloadMultiSigUser, type: 'address' }
+              new_fields << { name: :outerSigner, type: 'address' }
+            end
+          end
+          result[key] = new_fields
+        end
+      end
+      private_class_method :enrich_user_signed_types
+    end
+  end
+end

data/lib/hyperliquid/signing/signer.rb

@@ -50,6 +50,33 @@ module Hyperliquid
         sign_typed_data(typed_data)
       end
 
+      # Compute the action hash used by the L1 phantom-agent flow and by the multi-sig
+      # outer-envelope flow. Mirrors the official Python SDK's `action_hash` byte layout:
+      # keccak256(msgpack(action) + nonce(8B BE) + vault_flag + [vault_addr] + [expires_flag + expires_after])
+      # @param action [Hash, Array] The action payload (or list-shaped envelope for multi-sig L1)
+      # @param nonce [Integer] Nonce timestamp (ms)
+      # @param vault_address [String, nil] Optional vault address (lowercased before hashing)
+      # @param expires_after [Integer, nil] Optional expiration timestamp (ms)
+      # @return [String] 0x-prefixed hex of the 32-byte keccak256 hash
+      def self.compute_action_hash(action, nonce, vault_address: nil, expires_after: nil)
+        data = action.to_msgpack
+        data += [nonce].pack('Q>')
+
+        if vault_address.nil?
+          data += "\x00"
+        else
+          data += "\x01"
+          data += [vault_address.sub(/\A0x/i, '').downcase].pack('H*')
+        end
+
+        unless expires_after.nil?
+          data += "\x00"
+          data += [expires_after].pack('Q>')
+        end
+
+        "0x#{Eth::Util.keccak256(data).unpack1('H*')}"
+      end
+
       # Sign a user-signed action (transfers, withdrawals, etc.)
       # Uses direct EIP-712 typed data signing with HyperliquidSignTransaction domain
       # @param action [Hash] The action message to sign (will have chain fields injected)
@@ -92,41 +119,14 @@ module Hyperliquid
       # @param expires_after [Integer, nil] Optional expiration timestamp
       # @return [Hash] Phantom agent with source and connectionId
       def construct_phantom_agent(action, nonce, vault_address, expires_after)
-        # Compute action hash
-        # Maintains parity with official Python SDK
-        # data = msgpack(action) + nonce(8 bytes BE) + vault_flag + [vault_addr] + [expires_flag + expires_after]
-        # - Note: expires_flag is only included if expires_after exists. A bit odd but that's what the
-        #     Python SDK does.
-        data = action.to_msgpack
-        data += [nonce].pack('Q>') # 8-byte big-endian uint64
-
-        if vault_address.nil?
-          data += "\x00" # no vault flag
-        else
-          data += "\x01" # has vault flag
-          data += address_to_bytes(vault_address.downcase)
-        end
-
-        unless expires_after.nil?
-          data += "\x00" # expiration flag
-          data += [expires_after].pack('Q>') # 8-byte big-endian uint64
-        end
-
-        connection_id = Eth::Util.keccak256(data)
-
         {
           source: EIP712.source(testnet: @testnet),
-          connectionId: bin_to_hex(connection_id)
+          connectionId: self.class.compute_action_hash(action, nonce,
+                                                       vault_address: vault_address,
+                                                       expires_after: expires_after)
         }
       end
 
-      # Convert hex address to 20-byte binary
-      # @param address [String] Ethereum address with 0x prefix
-      # @return [String] 20-byte binary representation
-      def address_to_bytes(address)
-        [address.sub(/\A0x/i, '')].pack('H*')
-      end
-
       # Sign EIP-712 typed data using eth gem's built-in method
       # @param typed_data [Hash] Complete EIP-712 structure
       # @return [Hash] Signature components :r, :s, :v
@@ -141,13 +141,6 @@ module Hyperliquid
           v: signature[128, 2].to_i(16)
         }
       end
-
-      # Convert binary data to hex string with 0x prefix
-      # @param bin [String] Binary data
-      # @return [String] Hex string with 0x prefix
-      def bin_to_hex(bin)
-        "0x#{bin.unpack1('H*')}"
-      end
     end
   end
 end

data/lib/hyperliquid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperliquid
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

data/lib/hyperliquid.rb

@@ -8,6 +8,7 @@ require_relative 'hyperliquid/info'
 require_relative 'hyperliquid/cloid'
 require_relative 'hyperliquid/signing/eip712'
 require_relative 'hyperliquid/signing/signer'
+require_relative 'hyperliquid/signing/multi_sig'
 require_relative 'hyperliquid/exchange'
 require_relative 'hyperliquid/ws/client'
 

data/scripts/test_17_create_vault.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 17: createVault (L1 exchange action)
+#
+# Creates a new vault with the calling wallet as leader, using a $100 testnet
+# USDC seed (server-enforced minimum). On success, prints the new vault address
+# from response.data.
+#
+# WARNING: This is a real testnet action. The $100 seed is locked into the
+# created vault per Hyperliquid's vault lockup rules. Run intentionally —
+# do NOT wire into test_automated.rb.
+#
+# Skips with a warning if the wallet has < $100 perp USDC available.
+#
+# Usage:
+#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_17_create_vault.rb
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 17: createVault')
+
+state = sdk.info.user_state(sdk.exchange.address)
+withdrawable = state['withdrawable'].to_f
+puts "Wallet:       #{sdk.exchange.address}"
+puts "Withdrawable: $#{format('%.2f', withdrawable)}"
+puts
+
+if withdrawable < 100
+  puts red("SKIPPED: Need >= $100 perp USDC to seed a vault (have $#{format('%.2f', withdrawable)}).")
+  test_passed('Test 17 createVault')
+  exit 0
+end
+
+vault_name = "AgentVault#{Time.now.to_i}"
+vault_description = 'Vault created by hyperliquid-run integration test (test_17).'
+
+puts "Creating vault \"#{vault_name}\" with $100 seed..."
+result = sdk.exchange.create_vault(
+  name: vault_name,
+  description: vault_description,
+  initial_usd: 100
+)
+
+if api_error?(result)
+  puts red("createVault FAILED: #{result.inspect}")
+  test_passed('Test 17 createVault')
+  exit 1
+end
+
+unless result.is_a?(Hash) && result['status'] == 'ok'
+  $test_failed = true
+  puts red("Unexpected status: #{result.inspect}")
+end
+
+response_type = result.dig('response', 'type')
+unless response_type == 'createVault'
+  $test_failed = true
+  puts red("Expected response.type 'createVault', got: #{response_type.inspect}")
+end
+
+vault_address = result.dig('response', 'data')
+unless vault_address.is_a?(String) && vault_address.start_with?('0x') && vault_address.length == 42
+  $test_failed = true
+  puts red("Expected response.data to be a 0x-prefixed 40-hex-char vault address, got: #{vault_address.inspect}")
+end
+
+unless $test_failed
+  puts green("createVault OK: status=ok, response.type=#{response_type}, vault=#{vault_address}")
+end
+
+test_passed('Test 17 createVault')

data/scripts/test_all.rb

@@ -34,7 +34,8 @@ SCRIPTS = [
   'test_13_ws_l2_book.rb',
   'test_14_ws_candle.rb',
   'test_15_explorer.rb',
-  'test_16_send_to_evm_with_data.rb'
+  'test_16_send_to_evm_with_data.rb',
+  'test_17_create_vault.rb'
 ].freeze
 
 def green(text)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - carter2099
@@ -112,6 +112,7 @@ files:
 - lib/hyperliquid/exchange.rb
 - lib/hyperliquid/info.rb
 - lib/hyperliquid/signing/eip712.rb
+- lib/hyperliquid/signing/multi_sig.rb
 - lib/hyperliquid/signing/signer.rb
 - lib/hyperliquid/version.rb
 - lib/hyperliquid/ws/client.rb
@@ -131,6 +132,7 @@ files:
 - scripts/test_14_ws_candle.rb
 - scripts/test_15_explorer.rb
 - scripts/test_16_send_to_evm_with_data.rb
+- scripts/test_17_create_vault.rb
 - scripts/test_all.rb
 - scripts/test_automated.rb
 - scripts/test_helpers.rb