feat: add withdraw action

spacesailor24 · spacesailor24 · commit 3809b40aae22 · 2025-11-11T10:49:05.000-10:00
diff --git a/packages/apps/ability-hyperliquid/src/generated/lit-action.js b/packages/apps/ability-hyperliquid/src/generated/lit-action.js
diff --git a/packages/apps/ability-hyperliquid/src/generated/vincent-ability-metadata.json b/packages/apps/ability-hyperliquid/src/generated/vincent-ability-metadata.json
@@ -1,3 +1,3 @@
 {
-  "ipfsCid": "QmeB5SM3UxcFYKYNffhM4VMWXSnFoZPAH8iLAXTgYPPupp"
+  "ipfsCid": "QmZCeMB39rcjAsUFFDJhz7ac4gn6HnPfwpdJRMDkGc5Z8K"
 }
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-checks/index.ts b/packages/apps/ability-hyperliquid/src/lib/ability-checks/index.ts
@@ -4,3 +4,4 @@ export { transferPrechecks } from './transfer';
 export { spotTradePrechecks } from './spot';
 export { perpTradePrechecks } from './perp';
 export { cancelOrderPrechecks, cancelAllOrdersForSymbolPrechecks } from './cancel';
+export { withdrawPrechecks } from './withdraw';
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-checks/withdraw.ts b/packages/apps/ability-hyperliquid/src/lib/ability-checks/withdraw.ts
@@ -0,0 +1,74 @@
+import { ethers } from 'ethers';
+import * as hyperliquid from '@nktkas/hyperliquid';
+
+export type WithdrawPrechecksResult =
+  | WithdrawPrechecksResultSuccess
+  | WithdrawPrechecksResultFailure;
+
+export interface WithdrawPrechecksResultSuccess {
+  success: true;
+  availableBalance: string;
+  requiredBalance: string;
+}
+
+export interface WithdrawPrechecksResultFailure {
+  success: false;
+  reason: string;
+  availableBalance?: string;
+  requiredBalance?: string;
+}
+
+export interface WithdrawParams {
+  amount: string;
+}
+
+/**
+ * Check if withdrawal from Hyperliquid to L1 can be executed
+ */
+export async function withdrawPrechecks({
+  infoClient,
+  ethAddress,
+  params,
+}: {
+  infoClient: hyperliquid.InfoClient;
+  ethAddress: string;
+  params: WithdrawParams;
+}): Promise<WithdrawPrechecksResult> {
+  // Withdrawal comes from perp account
+  const clearinghouseState = await infoClient.clearinghouseState({
+    user: ethAddress,
+  });
+
+  const availableUsdcBalance = ethers.utils.parseUnits(
+    clearinghouseState.marginSummary.accountValue,
+    6, // USDC has 6 decimals
+  );
+
+  const requestedAmount = ethers.BigNumber.from(params.amount);
+  const minimumWithdrawAmount = ethers.utils.parseUnits('1', 6); // 1 USDC minimum (withdrawal fee)
+
+  // Check if requested amount is at least 1 USDC
+  if (requestedAmount.lt(minimumWithdrawAmount)) {
+    return {
+      success: false,
+      reason: `Withdrawal amount must be at least 1 USDC due to withdrawal fee. Requested: ${ethers.utils.formatUnits(requestedAmount, 6)} USDC`,
+      availableBalance: ethers.utils.formatUnits(availableUsdcBalance, 6),
+      requiredBalance: ethers.utils.formatUnits(minimumWithdrawAmount, 6),
+    };
+  }
+
+  if (availableUsdcBalance.lt(requestedAmount)) {
+    return {
+      success: false,
+      reason: `Insufficient perp balance for withdrawal. Available: ${ethers.utils.formatUnits(availableUsdcBalance, 6)} USDC, Requested: ${ethers.utils.formatUnits(requestedAmount, 6)} USDC`,
+      availableBalance: ethers.utils.formatUnits(availableUsdcBalance, 6),
+      requiredBalance: ethers.utils.formatUnits(requestedAmount, 6),
+    };
+  }
+
+  return {
+    success: true,
+    availableBalance: ethers.utils.formatUnits(availableUsdcBalance, 6),
+    requiredBalance: ethers.utils.formatUnits(requestedAmount, 6),
+  };
+}
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/cancel-order/cancel-all-orders.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/cancel-order/cancel-all-orders.ts
@@ -4,6 +4,7 @@ import { CancelRequest, CancelResponse, parser } from '@nktkas/hyperliquid/api/e
 import { signL1Action } from '@nktkas/hyperliquid/signing';
 
 import { LitActionPkpEthersWallet } from '../lit-action-pkp-ethers-wallet';
+import { getHyperliquidNonce } from '../get-hyperliquid-nonce';
 
 export type CancelAllOrdersResult = CancelAllOrdersResultSuccess | CancelAllOrdersResultFailure;
 
@@ -64,14 +65,7 @@ export async function cancelAllOrdersForSymbol({
     };
   }
 
-  // Generate deterministic nonce in runOnce
-  const nonceResponse = await Lit.Actions.runOnce(
-    { waitForResponse: true, name: 'HyperLiquidCancelAllOrdersNonce' },
-    async () => {
-      return Date.now().toString();
-    },
-  );
-  const nonce = parseInt(nonceResponse);
+  const nonce = await getHyperliquidNonce();
 
   // Construct cancel action for all orders
   const cancelAction = parser(CancelRequest.entries.action)({
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/cancel-order/cancel-order.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/cancel-order/cancel-order.ts
@@ -5,6 +5,7 @@ import { signL1Action } from '@nktkas/hyperliquid/signing';
 import { bigIntReplacer } from '@lit-protocol/vincent-ability-sdk';
 
 import { LitActionPkpEthersWallet } from '../lit-action-pkp-ethers-wallet';
+import { getHyperliquidNonce } from '../get-hyperliquid-nonce';
 
 export interface CancelSpotOrderParams {
   symbol: string; // e.g., "PURR/USDC"
@@ -47,15 +48,7 @@ export async function cancelOrder({
 
   // Create PKP wallet
   const pkpWallet = new LitActionPkpEthersWallet(pkpPublicKey);
-
-  // Generate deterministic nonce in runOnce
-  const nonceResponse = await Lit.Actions.runOnce(
-    { waitForResponse: true, name: 'HyperLiquidCancelOrderNonce' },
-    async () => {
-      return Date.now().toString();
-    },
-  );
-  const nonce = parseInt(nonceResponse);
+  const nonce = await getHyperliquidNonce();
 
   // Construct cancel action
   const cancelAction = parser(CancelRequest.entries.action)({
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/execute-perp-order.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/execute-perp-order.ts
@@ -10,6 +10,7 @@ import { signL1Action } from '@nktkas/hyperliquid/signing';
 import { bigIntReplacer } from '@lit-protocol/vincent-ability-sdk';
 
 import { LitActionPkpEthersWallet } from './lit-action-pkp-ethers-wallet';
+import { getHyperliquidNonce } from './get-hyperliquid-nonce';
 
 export type TimeInForce = 'Gtc' | 'Ioc' | 'Alo';
 
@@ -122,14 +123,7 @@ export async function executePerpOrder({
     );
   }
 
-  // Generate deterministic nonce for order in runOnce
-  const nonceResponse = await Lit.Actions.runOnce(
-    { waitForResponse: true, name: 'HyperLiquidPerpOrderNonce' },
-    async () => {
-      return Date.now().toString();
-    },
-  );
-  const nonce = parseInt(nonceResponse);
+  const nonce = await getHyperliquidNonce();
 
   // Determine order type configuration
   const orderType = params.orderType || { type: 'limit', tif: 'Gtc' };
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/execute-spot-order.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/execute-spot-order.ts
@@ -5,6 +5,7 @@ import { signL1Action } from '@nktkas/hyperliquid/signing';
 import { bigIntReplacer } from '@lit-protocol/vincent-ability-sdk';
 
 import { LitActionPkpEthersWallet } from './lit-action-pkp-ethers-wallet';
+import { getHyperliquidNonce } from './get-hyperliquid-nonce';
 
 export type TimeInForce = 'Gtc' | 'Ioc' | 'Alo';
 
@@ -58,15 +59,7 @@ export async function executeSpotOrder({
 
   // Create PKP wallet
   const pkpWallet = new LitActionPkpEthersWallet(pkpPublicKey);
-
-  // Generate deterministic nonce in runOnce
-  const nonceResponse = await Lit.Actions.runOnce(
-    { waitForResponse: true, name: 'HyperLiquidSpotOrderNonce' },
-    async () => {
-      return Date.now().toString();
-    },
-  );
-  const nonce = parseInt(nonceResponse);
+  const nonce = await getHyperliquidNonce();
 
   // Determine order type configuration
   const orderType = params.orderType || { type: 'limit', tif: 'Gtc' };
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/get-hyperliquid-nonce.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/get-hyperliquid-nonce.ts
@@ -0,0 +1,9 @@
+export async function getHyperliquidNonce() {
+  const nonceResponse = await Lit.Actions.runOnce(
+    { waitForResponse: true, name: 'HyperLiquidWithdrawNonce' },
+    async () => {
+      return Date.now().toString();
+    },
+  );
+  return parseInt(nonceResponse);
+}
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/index.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/index.ts
@@ -5,3 +5,4 @@ export { sendDepositTx } from './send-deposit-tx';
 export { transferUsdcTo } from './transfer-usdc-to';
 export { executeSpotOrder } from './execute-spot-order';
 export { executePerpOrder } from './execute-perp-order';
+export { withdrawUsdc } from './withdraw-usdc';
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/transfer-usdc-to.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/transfer-usdc-to.ts
@@ -10,6 +10,7 @@ import { ethers } from 'ethers';
 import { bigIntReplacer } from '@lit-protocol/vincent-ability-sdk';
 
 import { LitActionPkpEthersWallet } from './lit-action-pkp-ethers-wallet';
+import { getHyperliquidNonce } from './get-hyperliquid-nonce';
 
 export type TransferUsdcResult = {
   transferResult: SuccessResponse;
@@ -37,15 +38,7 @@ export async function transferUsdcTo({
     );
   }
 
-  // Generate deterministic nonce in runOnce
-  // This ensures all nodes use the same nonce and produce the same hash
-  const nonceResponse = await Lit.Actions.runOnce(
-    { waitForResponse: true, name: 'HyperLiquidTransferNonce' },
-    async () => {
-      return Date.now().toString();
-    },
-  );
-  const nonce = parseInt(nonceResponse);
+  const nonce = await getHyperliquidNonce();
 
   // Select chain ID and network based on testnet flag
   const signatureChainId = useTestnet
diff --git a/packages/apps/ability-hyperliquid/src/lib/ability-helpers/withdraw-usdc.ts b/packages/apps/ability-hyperliquid/src/lib/ability-helpers/withdraw-usdc.ts
@@ -0,0 +1,85 @@
+import * as hyperliquid from '@nktkas/hyperliquid';
+import {
+  Withdraw3Request,
+  Withdraw3Types,
+  SuccessResponse,
+  parser,
+} from '@nktkas/hyperliquid/api/exchange';
+import { signUserSignedAction } from '@nktkas/hyperliquid/signing';
+import { ethers } from 'ethers';
+import { bigIntReplacer } from '@lit-protocol/vincent-ability-sdk';
+
+import { LitActionPkpEthersWallet } from './lit-action-pkp-ethers-wallet';
+import { getHyperliquidNonce } from './get-hyperliquid-nonce';
+
+export type WithdrawUsdcResult = {
+  withdrawResult: SuccessResponse;
+};
+
+/**
+ * Withdraw funds from Hyperliquid Perp account to L1 (Arbitrum)
+ */
+export async function withdrawUsdc({
+  transport,
+  pkpPublicKey,
+  amount,
+  destination,
+  useTestnet = false,
+}: {
+  transport: hyperliquid.HttpTransport;
+  pkpPublicKey: string;
+  amount: string;
+  destination: string;
+  useTestnet?: boolean;
+}): Promise<WithdrawUsdcResult> {
+  // Create PKP wallet
+  const pkpWallet = new LitActionPkpEthersWallet(pkpPublicKey);
+  const nonce = await getHyperliquidNonce();
+
+  // Select chain ID and network based on testnet flag
+  const signatureChainId = useTestnet
+    ? '0x66eee' // Arbitrum Sepolia testnet chain ID: 421614
+    : '0xa4b1'; // Arbitrum mainnet chain ID: 42161
+  const hyperliquidChain = useTestnet ? 'Testnet' : 'Mainnet';
+
+  // Construct withdraw action
+  const withdrawAction = parser(Withdraw3Request.entries.action)({
+    type: 'withdraw3',
+    signatureChainId,
+    hyperliquidChain,
+    destination,
+    // Convert amount from raw units (e.g., "1000000" for 1.0 USDC) to formatted string (e.g., "1.0")
+    // Hyperliquid expects the amount as a string in human-readable format
+    amount: ethers.utils.formatUnits(amount, 6),
+    time: nonce,
+  });
+
+  // Withdraw3 is a user-signed action that uses EIP-712 typed data
+  const signature = await signUserSignedAction({
+    wallet: pkpWallet,
+    action: withdrawAction,
+    types: Withdraw3Types,
+  });
+
+  const withdrawResult = await Lit.Actions.runOnce(
+    { waitForResponse: true, name: 'HyperLiquidWithdrawRequest' },
+    async () => {
+      return JSON.stringify(
+        {
+          result: await transport.request('exchange', {
+            action: withdrawAction,
+            signature,
+            nonce,
+          }),
+        },
+        bigIntReplacer,
+        2,
+      );
+    },
+  );
+
+  const parsedWithdrawResult = JSON.parse(withdrawResult);
+  return {
+    withdrawResult: parsedWithdrawResult.result as SuccessResponse,
+  };
+}
diff --git a/packages/apps/ability-hyperliquid/src/lib/schemas.ts b/packages/apps/ability-hyperliquid/src/lib/schemas.ts
@@ -2,6 +2,7 @@ import { z } from 'zod';
 
 export const actionTypeSchema = z.enum([
   'deposit',
+  'withdraw',
   'transferToSpot',
   'transferToPerp',
   'spotBuy',
@@ -16,6 +17,20 @@ export const depositParamsSchema = z.object({
   amount: z.string().describe('Amount of USDC to deposit (minimum 6 USDC: 5 USDC + 1 USDC fee)'),
 });
 
+export const withdrawParamsSchema = z.object({
+  amount: z
+    .string()
+    .describe(
+      'Amount of USDC to withdraw from Hyperliquid to L1 (Arbitrum), specified in micro-units as a string (e.g., "1000000" means 1.0 USDC; 1 USDC = 1,000,000 micro-units).',
+    ),
+  destination: z
+    .string()
+    .optional()
+    .describe(
+      'Destination address on L1 (Arbitrum) to receive the withdrawn USDC. If not provided, defaults to the Agent Wallet PKP ETH address.',
+    ),
+});
+
 export const transferParamsSchema = z.object({
   amount: z
     .string()
@@ -119,6 +134,10 @@ export const abilityParamsSchema = z
     deposit: depositParamsSchema
       .optional()
       .describe('Deposit parameters (required for deposit action)'),
+    // Withdraw-specific params
+    withdraw: withdrawParamsSchema
+      .optional()
+      .describe('Withdraw parameters (required for withdraw action)'),
     // Transfer to spot or perps params
     transfer: transferParamsSchema
       .optional()
@@ -147,6 +166,7 @@ export const abilityParamsSchema = z
   .refine(
     (data) => {
       if (data.action === 'deposit') return !!data.deposit;
+      if (data.action === 'withdraw') return !!data.withdraw;
       if (data.action === 'transferToSpot' || data.action === 'transferToPerp')
         return !!data.transfer;
       if (data.action === 'spotBuy' || data.action === 'spotSell') return !!data.spot;
@@ -190,6 +210,7 @@ export const executeFailSchema = z.object({
 export const executeSuccessSchema = z.object({
   action: z.string().describe('Action that was executed'),
   txHash: z.string().optional().describe('Transaction hash (for deposit action)'),
+  withdrawResult: z.any().optional().describe('Withdraw result (for withdraw action)'),
   transferResult: z.any().optional().describe('Transfer result (for transferToSpot action)'),
   orderResult: z.any().optional().describe('Order result (for spotBuy/spotSell action)'),
   cancelResult: z
diff --git a/packages/apps/ability-hyperliquid/src/lib/types.ts b/packages/apps/ability-hyperliquid/src/lib/types.ts
@@ -3,6 +3,7 @@
  */
 export enum HyperliquidAction {
   DEPOSIT = 'deposit',
+  WITHDRAW = 'withdraw',
   TRANSFER_TO_SPOT = 'transferToSpot',
   TRANSFER_TO_PERP = 'transferToPerp',
   SPOT_BUY = 'spotBuy',
diff --git a/packages/apps/ability-hyperliquid/src/lib/vincent-ability.ts b/packages/apps/ability-hyperliquid/src/lib/vincent-ability.ts
diff --git a/packages/apps/ability-hyperliquid/test/e2e/withdraw.spec.ts b/packages/apps/ability-hyperliquid/test/e2e/withdraw.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- "ipfsCid": "QmeB5SM3UxcFYKYNffhM4VMWXSnFoZPAH8iLAXTgYPPupp"`
	`2`	`+ "ipfsCid": "QmZCeMB39rcjAsUFFDJhz7ac4gn6HnPfwpdJRMDkGc5Z8K"`
`3`	`3`	`}`