# 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

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

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:

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.