Skip to content

Commit d75e10d

Browse files
spacesailor24spacesailor24
committed
docs: init overview and deposit
1 parent 0744a0b commit d75e10d

File tree

2 files changed

+517
-0
lines changed

2 files changed

+517
-0
lines changed

‎docs/ability/official-abilities/hyperliquid/deposit.mdx‎

Lines changed: 377 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,377 @@
1+
---
2+
title: Deposit
3+
---
4+
5+
The `deposit` action enables Vincent Apps to bridge USDC from Arbitrum into a Vincent User's HyperCore mainnet perp balance using the Hyperliquid bridge contract.
6+
7+
<Note>
8+
The `deposit` action will only work if being executed on Arbitrum mainnet, and will **not** work
9+
for depositing to HyperCore testnet. To get test USDC on HyperCore testnet, follow the [testnet
10+
funding process](https://hyperliquid.gitbook.io/hyperliquid-docs/onboarding/testnet-faucet), or
11+
transfer test USDC from an existing HyperCore testnet account's balance.
12+
</Note>
13+
14+
## Prerequisites
15+
16+
Before executing the `deposit` action, the following conditions must be met:
17+
18+
- **Arbitrum RPC URL**: The `precheck` function of this Ability requires a valid Arbitrum mainnet RPC URL to perform the USDC transfer to the Hyperliquid bridge contract.
19+
- **USDC Balance on Arbitrum**: The Vincent User Agent Wallet must have sufficient USDC on Arbitrum to cover the deposit amount.
20+
- The minimum deposit amount for Hyperliquid is $5 USDC, do **not** deposit less as it will not be credited to the Vincent User's HyperCore perp balance.
21+
- **Native ETH for Gas**: The Vincent User Agent Wallet must have sufficient native ETH on Arbitrum to pay for the bridge transaction gas fees.
22+
23+
<Info>
24+
To learn more about executing Vincent Abilities, see the [Executing
25+
Abilities](/ability/explaining-abilities) guide.
26+
</Info>
27+
28+
## Executing the `precheck` Function
29+
30+
The `precheck` function validates some prerequisites for executing a deposit, without actually performing the operation.
31+
32+
For the `deposit` action, the `precheck` function will validate the following:
33+
34+
- The `useTestnet` parameter is set to `false`, or wasn't provided.
35+
- The Vincent User Agent Wallet has a non-zero balance of native ETH on Arbitrum to pay for the bridge transaction gas fees.
36+
- The deposit amount is greater than or equal to the minimum deposit amount for Hyperliquid.
37+
- The Vincent User Agent Wallet has a sufficient USDC balance on Arbitrum to cover the deposit amount.
38+
39+
<Tabs>
40+
<Tab title="Parameters">
41+
The `precheck` function requires the following parameters:
42+
43+
```typescript
44+
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
45+
46+
{
47+
/**
48+
* The action to perform (must be HyperliquidAction.DEPOSIT)
49+
*/
50+
action: HyperliquidAction.DEPOSIT;
51+
/**
52+
* Deposit parameters
53+
*/
54+
deposit: {
55+
/**
56+
* The amount of USDC to deposit in 6-decimal format.
57+
* Example: "5000000" = 5 USDC
58+
*/
59+
amount: string;
60+
};
61+
/**
62+
* An RPC endpoint for Arbitrum mainnet where the deposit will be executed.
63+
*/
64+
arbitrumRpcUrl: string;
65+
}
66+
```
67+
68+
</Tab>
69+
70+
<Tab title="Implementation">
71+
To execute `precheck`, you'll need to:
72+
73+
- Create an instance of the `VincentAbilityClient` using the `getVincentAbilityClient` function (imported from `@lit-protocol/vincent-app-sdk/abilityClient`)
74+
- Pass in the Ability's `bundledVincentAbility` object (imported from `@lit-protocol/vincent-ability-hyperliquid`)
75+
- Pass in the `ethersSigner` you'll be using to sign the request to Lit with your Delegatee private key
76+
- Use the `VincentAbilityClient` instance to call the `precheck` function
77+
78+
```typescript
79+
import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
80+
import { bundledVincentAbility, HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
81+
import { ethers } from 'ethers';
82+
83+
// Your delegatee signer (one of the delegatee signers for the Vincent App)
84+
const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY', provider);
85+
86+
// Create ability client
87+
const hyperliquidAbilityClient = getVincentAbilityClient({
88+
bundledVincentAbility,
89+
ethersSigner: delegateeSigner,
90+
});
91+
92+
// Run precheck
93+
const precheckResult = await hyperliquidAbilityClient.precheck(
94+
{
95+
action: HyperliquidAction.DEPOSIT,
96+
deposit: {
97+
amount: '5000000', // 5 USDC in 6-decimal format
98+
},
99+
arbitrumRpcUrl: 'https://arb1.arbitrum.io/rpc',
100+
},
101+
{
102+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
103+
},
104+
);
105+
106+
if (precheckResult.success) {
107+
console.log('Deposit precheck passed, ready to execute');
108+
} else {
109+
// Handle different types of failures
110+
if (precheckResult.runtimeError) {
111+
console.error('Runtime error:', precheckResult.runtimeError);
112+
}
113+
if (precheckResult.schemaValidationError) {
114+
console.error('Schema validation error:', precheckResult.schemaValidationError);
115+
}
116+
if (precheckResult.result) {
117+
console.error('Deposit precheck failed:', precheckResult.result.reason);
118+
}
119+
}
120+
```
121+
122+
</Tab>
123+
124+
<Tab title="Response">
125+
### Success
126+
127+
A successful `precheck` response will contain:
128+
129+
```typescript
130+
{
131+
/**
132+
* The action that was prechecked
133+
*/
134+
action: 'deposit';
135+
}
136+
```
137+
138+
### Failure
139+
140+
A failure `precheck` response will contain:
141+
142+
```typescript
143+
{
144+
/**
145+
* The action that was prechecked
146+
*/
147+
action: 'deposit';
148+
/**
149+
* The reason the precheck failed, such as insufficient USDC balance,
150+
* insufficient native ETH for gas, or invalid RPC URL.
151+
*/
152+
reason: string;
153+
/**
154+
* The available USDC balance in the Vincent User's Arbitrum account (optional)
155+
*/
156+
availableBalance?: string;
157+
}
158+
```
159+
160+
</Tab>
161+
</Tabs>
162+
163+
## Executing the `execute` Function
164+
165+
The `execute` function performs the actual deposit by bridging USDC from Arbitrum to Vincent User's HyperCore perp balance, by transferring the USDC to the Hyperliquid bridge contract.
166+
167+
For the `deposit` action, the `execute` function will:
168+
169+
- Transfer the specified amount of USDC from the Vincent User Agent Wallet's Arbitrum account to the Hyperliquid bridge contract.
170+
- Return the transaction hash of the deposit transaction on Arbitrum.
171+
172+
<Tabs>
173+
<Tab title="Parameters">
174+
The `execute` function requires the following parameters, note that the `arbitrumRpcUrl` parameter is not used because the Ability will use the Arbitrum RPC URL supplied by the Lit Nodes:
175+
176+
```typescript
177+
import { HyperliquidAction } from '@lit-protocol/vincent-ability-hyperliquid';
178+
179+
{
180+
/**
181+
* The action to perform (must be HyperliquidAction.DEPOSIT)
182+
*/
183+
action: HyperliquidAction.DEPOSIT;
184+
/**
185+
* Deposit parameters
186+
*/
187+
deposit: {
188+
/**
189+
* The amount of USDC to deposit in 6-decimal format.
190+
* Example: "15000000" = 15 USDC
191+
*/
192+
amount: string;
193+
};
194+
}
195+
```
196+
197+
</Tab>
198+
199+
<Tab title="Implementation">
200+
The `execute` function can be executed using the same `VincentAbilityClient` instance as used for the `precheck` function:
201+
202+
```typescript
203+
const executeResult = await hyperliquidAbilityClient.execute(
204+
{
205+
action: HyperliquidAction.DEPOSIT,
206+
deposit: {
207+
amount: '15000000', // 15 USDC in 6-decimal format
208+
},
209+
},
210+
{
211+
delegatorPkpEthAddress: '0x...', // The Vincent User's Vincent Wallet address
212+
},
213+
);
214+
215+
if (executeResult.success) {
216+
const { txHash } = executeResult.result;
217+
console.log('Deposit transaction:', txHash);
218+
219+
// Wait for the transaction to be confirmed on Arbitrum
220+
const provider = new ethers.providers.JsonRpcProvider('https://arb1.arbitrum.io/rpc');
221+
const receipt = await provider.waitForTransaction(txHash, 1);
222+
console.log('Transaction confirmed:', receipt.status === 1);
223+
} else {
224+
// Handle different types of failures
225+
if (executeResult.runtimeError) {
226+
console.error('Runtime error:', executeResult.runtimeError);
227+
}
228+
if (executeResult.schemaValidationError) {
229+
console.error('Schema validation error:', executeResult.schemaValidationError);
230+
}
231+
if (executeResult.result) {
232+
console.error('Deposit execution failed:', executeResult.result.reason);
233+
}
234+
}
235+
```
236+
237+
</Tab>
238+
239+
<Tab title="Response">
240+
**Success Response**
241+
242+
A successful `execute` response will contain:
243+
244+
```typescript
245+
{
246+
/**
247+
* The action that was executed
248+
*/
249+
action: 'deposit';
250+
/**
251+
* The hash of the deposit transaction on Arbitrum
252+
*/
253+
txHash: string;
254+
}
255+
```
256+
257+
**Failure Response**
258+
259+
A failure `execute` response will contain:
260+
261+
```typescript
262+
{
263+
/**
264+
* The action that was executed
265+
*/
266+
action: 'deposit';
267+
/**
268+
* The reason the execution failed, such as insufficient USDC balance,
269+
* insufficient native ETH for gas, or transaction failure.
270+
*/
271+
reason?: string;
272+
}
273+
```
274+
275+
</Tab>
276+
</Tabs>
277+
278+
## Important Considerations
279+
280+
<AccordionGroup>
281+
<Accordion title="Deposit Processing Time" icon="clock">
282+
After successfully executing a deposit transaction on Arbitrum, it takes some time for the funds to appear in the Vincent User's Hyperliquid portfolio. The transaction must be confirmed on Arbitrum before Hyperliquid's bridge processes the deposit.
283+
</Accordion>
284+
285+
<Accordion title="USDC Decimal Format" icon="hashtag">
286+
USDC on Arbitrum uses **6 decimals**. When specifying the deposit amount, use the 6-decimal
287+
format:
288+
289+
- 5 USDC = `"5000000"`
290+
- 15 USDC = `"15000000"`
291+
- 100 USDC = `"100000000"`
292+
293+
</Accordion>
294+
295+
<Accordion title="Testnet Not Supported" icon="triangle-exclamation">
296+
The `deposit` action only works on **Hyperliquid mainnet**. If you set `useTestnet: true`, the
297+
deposit action will fail. To get test USDC on Hyperliquid testnet, you must first make a minimum 5
298+
USDC deposit on mainnet, then claim test USDC through the [Hyperliquid testnet
299+
faucet](https://hyperliquid.gitbook.io/hyperliquid-docs/onboarding/testnet-faucet).
300+
</Accordion>
301+
302+
<Accordion title="Gas Fees on Arbitrum" icon="gas-pump">
303+
The Vincent User's Vincent Wallet must have sufficient native ETH on Arbitrum to pay for the
304+
bridge transaction gas fees. Ensure the wallet has at least a small amount of ETH before
305+
attempting a deposit.
306+
</Accordion>
307+
308+
<Accordion title="Verifying Deposit Success" icon="check">
309+
After the deposit transaction is confirmed on Arbitrum, you can verify the funds arrived in the Vincent User's Hyperliquid portfolio by checking the clearinghouse state using a [Hyperliquid SDK](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api), or by using the [Hyperliquid API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-perpetuals-asset-contexts-includes-mark-price-current-funding-open-interest-etc).
310+
</Accordion>
311+
</AccordionGroup>
312+
313+
## Reference Implementation
314+
315+
For a complete working example showing the full deposit workflow including balance verification, see the [deposit.spec.ts](https://github.com/LIT-Protocol/Vincent/blob/main/packages/apps/ability-hyperliquid/test/e2e/deposit.spec.ts) end-to-end test in the `ability-hyperliquid` package.
316+
317+
## Next Steps
318+
319+
Explore the rest of the supported Hyperliquid actions:
320+
321+
<CardGroup cols={3}>
322+
323+
<Card title="Withdraw" href="/ability/official-abilities/hyperliquid/withdraw" icon="arrow-up" />
324+
325+
<Card
326+
title="Send Spot Asset"
327+
href="/ability/official-abilities/hyperliquid/send-spot-asset"
328+
icon="coins"
329+
/>
330+
331+
<Card
332+
title="Send Perp USDC"
333+
href="/ability/official-abilities/hyperliquid/send-perp-usdc"
334+
icon="dollar-sign"
335+
/>
336+
337+
<Card
338+
title="Transfer to Spot"
339+
href="/ability/official-abilities/hyperliquid/transfer-to-spot"
340+
icon="arrow-right"
341+
/>
342+
343+
<Card
344+
title="Transfer to Perp"
345+
href="/ability/official-abilities/hyperliquid/transfer-to-perp"
346+
icon="arrow-left"
347+
/>
348+
349+
<Card
350+
title="Spot Buy"
351+
href="/ability/official-abilities/hyperliquid/spot-buy"
352+
icon="shopping-cart"
353+
/>
354+
355+
<Card title="Spot Sell" href="/ability/official-abilities/hyperliquid/spot-sell" icon="tag" />
356+
357+
<Card
358+
title="Perp Long"
359+
href="/ability/official-abilities/hyperliquid/perp-long"
360+
icon="arrow-up-right"
361+
/>
362+
363+
<Card
364+
title="Perp Short"
365+
href="/ability/official-abilities/hyperliquid/perp-short"
366+
icon="arrow-down-right"
367+
/>
368+
369+
<Card title="Cancel Order" href="/ability/official-abilities/hyperliquid/cancel-order" icon="ban" />
370+
371+
<Card
372+
title="Cancel All Orders"
373+
href="/ability/official-abilities/hyperliquid/cancel-all-orders-for-symbol"
374+
icon="trash"
375+
/>
376+
377+
</CardGroup>

0 commit comments

Comments
 (0)