hyperliquid 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bb8af9ff28e902372f37910705473b980d432cf4a04485dbe5999e7fa6edc7e
-  data.tar.gz: e7176efc9fd95c1662b36ec7b8f5536192d8ce3e41624f9b341eca5e79de079a
+  metadata.gz: c7969eed04a0b822b7be2c29c3ab57f97f077eaf8ed245bc48cb4916fd6b5836
+  data.tar.gz: d37e1acbf31a1e26454071ede7c83fcccf842bf9524835def63a652e77fff1af
 SHA512:
-  metadata.gz: 79d01ffef7d490e185e191285dab90adcd339b03c8f2936ab8eaccb1fba6bc832a76aa49e2cee3db354608a5ce53e92afda6c6efec5d8b2cafc0c1e9a51f7b44
-  data.tar.gz: c313423aab3b257d81b7447c840502025f1a92cf857064c614678be2022b533ce7e85a89bedf0aaedd371c5781425962ee48b8f8c9ac7be98f3940b08c756510
+  metadata.gz: 1a7bc66c9acd82975bb1e5929d2f4b77469c5e52b3c9824f7ce5306ad642c1e065531d6f4c20134cdab85c350b2f694736c5a414ee6e7a564d35abc658ed1074
+  data.tar.gz: 9898cba2cbf564dff73f950a29423dd5f42ab2fddf62458418d365546893dabdc5f3ddf159f1af31c7e6254ff02aeaa1a77ca0c63f6198931ee291319daaab82

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.4.0] - 2026-05-05
+
+### New Exchange actions
+
+- `Exchange#send_to_evm_with_data(destination:, token:, amount:, data:, ...)` — user-signed; transfers Core assets to HyperEVM with arbitrary calldata for `ICoreReceiveWithData` contracts. Adds `SEND_TO_EVM_WITH_DATA_TYPES` (first user-signed action using `bytes`). Includes signature-parity regression specs against captured `eth_account` fixtures to lock down eth gem's `bytes` handling.
+- `Exchange#agent_send_asset(...)` — agent-signed counterpart to `send_asset` (destination must equal the agent's principal).
+- `Exchange#hip3_liquidator_transfer(dex:, usdc:, to_dex:)` — deposit/withdraw to an HIP-3 DEX backstop in 1e-6 quote-token units.
+- `Exchange#borrow_lend(token:, action:, amount:, is_isolated:)` — HIP-2 supply/withdraw/repay/borrow (L1 action). Companion to the four HIP-2 info methods. `amount` is nullable for full-position ops.
+- `Exchange#sub_account_modify(sub_account_user:, name:)` — rename a sub-account (L1 action).
+- `Exchange#link_staking_user(staking_user:, ...)` — link staking + trading accounts for fee discount (user-signed EIP-712). Adds `LINK_STAKING_USER_TYPES`.
+
 ## [1.3.0] - 2026-04-30
 
 ### New transport

data/CLAUDE.md

@@ -63,6 +63,8 @@ The signing chain in `lib/hyperliquid/signing/` must exactly match the official
 
 Any change to signing must maintain parity with the Python SDK or transactions will be rejected by the exchange.
 
+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.
+
 ### 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

@@ -893,6 +893,166 @@ module Hyperliquid
       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'
+    # @param token [Integer] HIP-2 token ID (e.g. 0 for USDC)
+    # @param amount [String, Numeric, nil] Amount to operate on; pass nil to use the full position
+    # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @return [Hash] Exchange response
+    def borrow_lend(operation:, token:, amount: nil, vault_address: nil)
+      nonce = timestamp_ms
+      action = {
+        type: 'borrowLend',
+        operation: operation,
+        token: token,
+        amount: amount&.to_s
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Rename a sub-account (`subAccountModify` L1 action).
+    # @param sub_account_user [String] Sub-account wallet address to rename
+    # @param name [String] New sub-account name (1–16 characters)
+    # @return [Hash] Exchange response
+    def sub_account_modify(sub_account_user:, name:)
+      nonce = timestamp_ms
+      action = {
+        type: 'subAccountModify',
+        subAccountUser: sub_account_user,
+        name: name
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Link a staking account to a trading account for fee-discount attribution
+    # (`linkStakingUser` user-signed action).
+    # The trading user initiates with `is_finalize: false`; the staking user finalizes
+    # the permanent link with `is_finalize: true`. The `user` field is the *other*
+    # account address in each direction.
+    # @param user [String] The counterpart account address (staking address when initiating, trading when finalizing)
+    # @param is_finalize [Boolean] False = trading user initiates, true = staking user finalizes
+    # @return [Hash] Exchange response
+    def link_staking_user(user:, is_finalize:)
+      nonce = timestamp_ms
+      action = {
+        type: 'linkStakingUser',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        user: user,
+        isFinalize: is_finalize,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { user: user, isFinalize: is_finalize, nonce: nonce },
+        'HyperliquidTransaction:LinkStakingUser',
+        Signing::EIP712::LINK_STAKING_USER_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Move assets between DEX instances on behalf of an agent's principal
+    # (`agentSendAsset` L1 action). Unlike `send_asset` (which is user-signed),
+    # this is signed by an agent and the destination must equal the agent's
+    # principal address. `source_dex`/`destination_dex` accept "" (default USDC
+    # perp DEX) and "spot" (spot trading) per protocol convention.
+    # @param destination [String] Destination wallet address (must match the agent's principal)
+    # @param source_dex [String] Source DEX identifier
+    # @param destination_dex [String] Destination DEX identifier
+    # @param token [String] Token in "tokenName:tokenId" format
+    # @param amount [String, Numeric] Amount to send
+    # @param from_sub_account [String] Source sub-account address, or empty string for the principal
+    # @return [Hash] Exchange response
+    def agent_send_asset(destination:, source_dex:, destination_dex:, token:, amount:,
+                         from_sub_account: '')
+      nonce = timestamp_ms
+      action = {
+        type: 'agentSendAsset',
+        destination: destination,
+        sourceDex: source_dex,
+        destinationDex: destination_dex,
+        token: token,
+        amount: amount.to_s,
+        fromSubAccount: from_sub_account,
+        nonce: nonce
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Deposit to or withdraw from an HIP-3 DEX's backstop liquidator
+    # (`hip3LiquidatorTransfer` L1 action). `ntl` is denominated in 1e-6 quote
+    # tokens and the protocol requires it to be a multiple of 1_000_000_000
+    # (i.e. $1,000 increments).
+    # @param dex [String] HIP-3 DEX identifier
+    # @param ntl [Integer] Notional amount in 1e-6 quote tokens (multiple of 1_000_000_000)
+    # @param is_deposit [Boolean] True to deposit into the backstop, false to withdraw
+    # @return [Hash] Exchange response
+    def hip3_liquidator_transfer(dex:, ntl:, is_deposit:)
+      nonce = timestamp_ms
+      action = { type: 'hip3LiquidatorTransfer', dex: dex, ntl: ntl, isDeposit: is_deposit }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Transfer an asset from Core to HyperEVM with an arbitrary calldata payload
+    # (`sendToEvmWithData` user-signed action). Intended for `ICoreReceiveWithData`
+    # contracts that react atomically to the deposit. `data` accepts a hex string
+    # ('0x' or '0x...'); the EIP-712 signer hashes it as `bytes`.
+    # `destination_recipient` is NOT lowercased — `address_encoding` may be
+    # 'base58' for non-EVM target chains, where lowercasing would corrupt the value.
+    # @param token [String] Token symbol (e.g. "USDC")
+    # @param amount [String, Numeric] Amount as UnsignedDecimal (NOT wei); coerced via to_s
+    # @param source_dex [String] Source DEX identifier (e.g. "spot")
+    # @param destination_recipient [String] Recipient address on the destination chain (hex or base58)
+    # @param address_encoding [String] One of 'hex' or 'base58'
+    # @param destination_chain_id [Integer] Target EVM chain id (e.g. 998 for HyperEVM testnet)
+    # @param gas_limit [Integer] Gas limit for the destination EVM call
+    # @param data [String] ABI calldata hex string ('0x' for empty payload)
+    # @return [Hash] Exchange response
+    def send_to_evm_with_data(token:, amount:, source_dex:, destination_recipient:,
+                              address_encoding:, destination_chain_id:, gas_limit:, data: '0x')
+      nonce = timestamp_ms
+      action = {
+        type: 'sendToEvmWithData',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        token: token,
+        amount: amount.to_s,
+        sourceDex: source_dex,
+        destinationRecipient: destination_recipient,
+        addressEncoding: address_encoding,
+        destinationChainId: destination_chain_id.to_i,
+        gasLimit: gas_limit.to_i,
+        data: data,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { token: token, amount: amount.to_s, sourceDex: source_dex,
+          destinationRecipient: destination_recipient, addressEncoding: address_encoding,
+          destinationChainId: destination_chain_id.to_i, gasLimit: gas_limit.to_i,
+          data: data, nonce: nonce },
+        'HyperliquidTransaction:SendToEvmWithData',
+        Signing::EIP712::SEND_TO_EVM_WITH_DATA_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
     # Clear the asset metadata cache
     # Call this if metadata has been updated
     def reload_metadata!

data/lib/hyperliquid/signing/eip712.rb

@@ -121,6 +121,30 @@ module Hyperliquid
         ]
       }.freeze
 
+      LINK_STAKING_USER_TYPES = {
+        'HyperliquidTransaction:LinkStakingUser': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :user, type: 'address' },
+          { name: :isFinalize, type: 'bool' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
+      SEND_TO_EVM_WITH_DATA_TYPES = {
+        'HyperliquidTransaction:SendToEvmWithData': [
+          { name: :hyperliquidChain,     type: 'string' },
+          { name: :token,                type: 'string' },
+          { name: :amount,               type: 'string' },
+          { name: :sourceDex,            type: 'string' },
+          { name: :destinationRecipient, type: 'string' },
+          { name: :addressEncoding,      type: 'string' },
+          { name: :destinationChainId,   type: 'uint32' },
+          { name: :gasLimit,             type: 'uint64' },
+          { name: :data,                 type: 'bytes'  },
+          { name: :nonce,                type: 'uint64' }
+        ]
+      }.freeze
+
       class << self
         # Domain for L1 actions (orders, cancels, leverage, etc.)
         # @return [Hash] EIP-712 domain configuration

data/lib/hyperliquid/version.rb

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

data/scripts/test_16_send_to_evm_with_data.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 16: sendToEvmWithData (user-signed exchange action)
+#
+# Mirrors the TS SDK's `tests/api/exchange/sendToEvmWithData.test.ts`:
+#   1. Top up spot USDC by 2 (via usd_class_transfer perp -> spot).
+#   2. Submit one real sendToEvmWithData action sending 1 USDC to 0x...01
+#      on HyperEVM testnet (chain 998) with empty calldata.
+#   3. Assert response is { status: 'ok', response: { type: 'default' } }.
+#
+# This funds-moving test sends 1 testnet USDC to 0x...01 (effectively burned —
+# no contract is there to redirect it). Same bar the TS SDK uses for its own
+# test suite.
+#
+# Skips with a warning if the wallet is on unified account (usd_class_transfer
+# is disabled in that mode and the top-up cannot run).
+#
+# Usage:
+#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_16_send_to_evm_with_data.rb
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 16: sendToEvmWithData')
+
+abstraction = sdk.info.user_abstraction(sdk.exchange.address)
+if abstraction == 'unifiedAccount'
+  puts "SKIPPED: Wallet has unified account active (abstraction=#{abstraction.inspect})."
+  puts '  usd_class_transfer top-up step is disabled by the exchange when balances are unified.'
+  test_passed('Test 16 sendToEvmWithData')
+  exit 0
+end
+
+puts 'Topping up spot USDC by $2 (perp -> spot)...'
+top_up = sdk.exchange.usd_class_transfer(amount: '2', to_perp: false)
+dump_status(top_up)
+if api_error?(top_up)
+  puts red('Top-up failed; aborting before sendToEvmWithData.')
+  test_passed('Test 16 sendToEvmWithData')
+  exit 1
+end
+puts green('Top-up successful.')
+puts
+
+wait_with_countdown(WAIT_SECONDS, 'Waiting before sendToEvmWithData...')
+
+puts 'Sending 1 USDC to 0x...01 on HyperEVM testnet (chain 998) with empty calldata...'
+result = sdk.exchange.send_to_evm_with_data(
+  token: 'USDC',
+  amount: '1',
+  source_dex: 'spot',
+  destination_recipient: '0x0000000000000000000000000000000000000001',
+  address_encoding: 'hex',
+  destination_chain_id: 998,
+  gas_limit: 200_000,
+  data: '0x'
+)
+
+if api_error?(result)
+  puts red("sendToEvmWithData FAILED: #{result.inspect}")
+  test_passed('Test 16 sendToEvmWithData')
+  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 == 'default'
+  $test_failed = true
+  puts red("Expected response.type 'default', got: #{response_type.inspect}")
+end
+
+puts green("sendToEvmWithData OK: status=ok, response.type=#{response_type}") unless $test_failed
+
+test_passed('Test 16 sendToEvmWithData')

data/scripts/test_all.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - carter2099
@@ -130,6 +130,7 @@ files:
 - scripts/test_13_ws_l2_book.rb
 - scripts/test_14_ws_candle.rb
 - scripts/test_15_explorer.rb
+- scripts/test_16_send_to_evm_with_data.rb
 - scripts/test_all.rb
 - scripts/test_automated.rb
 - scripts/test_helpers.rb