---
# System prepended metadata

title: Miden × Hyperliquid Trading Integration — Requirements Document

---

# Miden × Hyperliquid Trading Integration — Requirements Document

**Status:** Draft  
**Owner:** Socket?  
**Goal:** Enable Alice to trade on Hyperliquid directly from her private Miden account or multisig, with one click, while preserving privacy and ensuring smooth bridging and margin management.

---

# 1. Background & Motivation

Miden serves as a **private balance sheet** for users. High-volume or active users (like traders) want to keep their funds private while interacting with public trading venues on chains as **Hyperliquid**, **Solana**, **Base**, or **Ethereum**.

The first integration targets **Hyperliquid**, because:

- It is a high-throughput, crypto-native trading venue  
- It offers **perpetual futures**, requiring margin management  
- It benefits from fast, automated bridging flows  
- It is an ideal fit for Miden’s **private custody → public execution** model

This document focuses exclusively on the Hyperliquid integration.

---

# 2. User Story: Alice

## As Alice, I want to:

1. **Hold funds privately** in a Miden account or multisig.  
2. **Open trades on Hyperliquid with one click or one command.**  
3. **For spot trades:** automatically bridge funds in and out.  
4. **For perpetual trades:**  
   - Open a position  
   - Monitor my position (via Hyperliquid API queries)  
   - Add margin via a one-click bridge action  
   - Close the position and receive settlement back into Miden  
5. **Remain private:**  
   - External observers cannot tell that Alice bridged to Hyperliquid or back.  
   - Bridge and Miden operator may see metadata; the public should not.

---

# 3. Core Flows

## 3.1 Spot Trading Flow

### User Interaction Example

```sh
miden trade spot --exchange hyperliquid --pair BTC-USDC --amount 1000
```

### Required Flow

1. **Balance Check:**  
   Query Alice’s private balance inside Miden.

2. **Bridge-Out:**  
   - Create a private-to-public outbound bridge transfer from Miden to Hyperliquid’s deposit endpoint.  
   - Ensure no leakage of Alice’s identity.

3. **Trade Execution:**  
   - Submit a spot trade order via Hyperliquid API.  
   - Receive execution confirmation.

4. **Bridge-In (Settlement):**  
   - After settlement, remaining assets must be bridged back into Miden.  
   - Funds return as **private notes**.

5. **Portfolio Update:**  
   - Alice sees updated balances inside her private Miden account.

---

## 3.2 Perpetual Futures Flow

### User Interaction Example

```sh
miden trade perp open --exchange hyperliquid --pair ETH-PERP --margin 2000 --leverage 5
```

### Required Flow

1. **Margin Bridge-Out:**  
   Transfer margin from Miden privately to Hyperliquid.

2. **Open Position:**  
   - Submit order to Hyperliquid.  
   - Retrieve position ID.

3. **Position Monitoring:**  
   Support two models:  
   - Direct API polling  
   - Optional “position oracle” run by Miden

4. **Add Margin:**  
   - Alice triggers “Add margin”  
   - Bridge-out additional funds privately  
   - Hyperliquid receives the top-up

5. **Close Position:**  
   - Client requests position close via Hyperliquid API  
   - Settlement completes

6. **Bridge-In Back to Miden:**  
   - Settlement funds are bridged back  
   - Converted into private notes  
   - Portfolio updates inside Miden

---

# 4. Privacy Requirements

## 4.1 Goals

- Public observers **must not** link bridge events to Alice.  
- Miden addresses or private identifiers must **not** leak.  
- Bridge operator may know; the world should not.

## 4.2 Minimum Technical Requirements

### Outbound Privacy
- Source is a private note.  
- No direct exposure of Alice’s identity.  
- Optionally support batching, relayers, or timing obfuscation.

### Inbound Privacy
- Returning funds must become private notes without linking to Hyperliquid deposits.

### Visibility Model
- Block explorer does **not** show “Alice bridged to Hyperliquid.”  
- At most: “A private account bridged X assets.”

---

# 5. Functional Requirements

## FR-1: Client Command Interface

Unified API for the Miden client:

```sh
client.external_trade(chainId: 4, long, USD-ETH, )
```

## FR-2: Bridge Abstraction Layer

- Generic interface for bridge-out and bridge-in  
- Must support future chains (Solana, Base, Ethereum)

## FR-3: Private Balance Verification

- Query private Miden balances  
- Multi-asset support (USDC, ETH, etc.)

## FR-4: Trade Execution Engine

Handles Hyperliquid API operations:

- Spot order placement  
- Perp order placement  
- Position queries  
- Margin adjustments  
- Closing positions

## FR-5: Settlement Listener

- Detect settlement on Hyperliquid  
- Trigger automatic bridge-in process

## FR-6: Privacy-Preserving Bridge

- Outbound and inbound bridging must not reveal Alice’s identity  
- Compatible with stronger privacy upgrades later

---

# 6. Non-Functional Requirements

## NFR-1: Security
- API keys stored securely (encrypted local store or secure enclave)  
- No private Miden data sent externally

## NFR-2: Performance
- Target: bridge-out < 10s (MVP), < 2s (future)  
- Position monitoring refresh < 2s

## NFR-3: Compliance
- Architecture allows future:
  - Provable compliance (e.g., Predicate)  
  - Allowlisting  
  - Transaction attestation

## NFR-4: Auditability
- Client logs bridging events, trades, and settlements locally

---

# 7. Open Questions

1. What Hyperliquid authentication model should be used?  
   - API keys, subaccounts, MPC signing?

2. Who operates the bridge?  
   - Miden, third-party, or relayer network?

3. Can bridging be made private even from the operator?  
   - Possible with relayers + ZK, may be long-term.

4. Fee model:  
   - Who pays gas / relayer fees?  
   - Deduct from Miden balance or require prepay?

---

# 8. Roadmap

## Phase 1: MVP
- One-click spot trades  
- Basic bridge-out + bridge-in  
- Open perps  
- Manual margin top-up  
- Basic position polling

## Phase 2: Improved UX
- Automated settlement tracking  
- Live PnL dashboard  
- One-click margin addition  
- Privacy improvements (batching/relayers)

## Phase 3: Production
- Ultra-fast bridging  
- Automated settlement flows  
- Multi-chain support (Solana, Base, Ethereum)  
- Compliance tooling  
- Miden multisig integration  
- Cross-exchange portfolio management

---

# 9. Acceptance Criteria

A feature is complete when:

- Alice can open a spot or perp trade with one click.  
- Bridge-out and bridge-in work automatically.  
- No public observer can link Alice to Hyperliquid transactions.  
- Perp positions can be monitored and margin added.  
- Closing positions returns funds to private Miden notes.  
- UX is smooth and flows are logged.
