hyperliquid-hip-1-deployment-calculator

HIP-1 token deployment validator and budget calculator for Hyperliquid.

🌐 Live App: hl-listing-calc.0xkaz.com

Dashboard Preview

Scope

Validate HIP-1 token parameters (name, weiDecimals, szDecimals, maxSupply) before deployment
Estimate HYPE-denominated Dutch auction budget and USDC liquidity needs
Generate operator checklists for testnet and mainnet dry-runs
Provide a web UI for interactive parameter exploration and validation

Architecture

src/
├── types.ts            # Type definitions for token specs, validation results, deployment budgets
├── rules.ts            # Core validation engine (Hip1ValidationEngine)
├── rules.test.ts       # Comprehensive test suite with valid/invalid/borderline fixtures
└── App.tsx             # React web interface (Phase 2)

Development

Requirements

Node.js 20.19+, 22.13+, or 24+
npm 10+

Setup

npm install
npm run dev          # Start dev server (http://localhost:5173)
npm run build        # Build for production
npm test             # Run test suite
npm run type-check   # TypeScript type checking

Phase Status

✅ Phase 1: Rule Engine — Complete
- Hip1ValidationEngine class with validation functions
- All constraints from official spec validated
- Test fixtures for valid/invalid/borderline cases
✅ Phase 2: CLI & Web UI — Complete
- CLI tool for batch validation and checklist generation
- Interactive React web app with real-time validation
- JSON input/output for automation
- Testnet/mainnet deployment checklists

Usage

Web UI (Interactive)

npm run dev
# Open http://localhost:5173 in browser
# - Fill in token parameters in "Token Spec" tab
# - Configure HIP-2 liquidity in "HIP-2 Hyperliquidity" tab
# - Click "Validate Parameters" to see results
# - Download JSON report

CLI (Command Line)

Validate token parameters

npm run cli -- validate --input examples/valid-token.json --hype-price 5.25

Output:

═══════════════════════════════════════════════════════
HIP-1 TOKEN DEPLOYMENT VALIDATION REPORT
═══════════════════════════════════════════════════════

Status: ✅ VALID

TOKEN SPECIFICATION:
  Name:          MEME
  weiDecimals:   8
  szDecimals:    3
  Lot size:      10^5 = 100000 atomic units
  maxSupply:     1000000000000000

ESTIMATED BUDGET:
  Target Gas Bid:  500 HYPE
  Safety Buffer:   25%
  Estimated HYPE:  625 HYPE
  USDC Liquidity:  251.5 USDC

VALIDATION MESSAGES:
  [INFO]
    ℹ️  weiDecimals: weiDecimals=8 matches USDC (common for Hyperliquid tokens)
    ℹ️  szDecimals: Lot size: 1 lot = 10^5 wei = 100000 atomic units
    ...
═══════════════════════════════════════════════════════

Generate deployment checklist

npm run cli -- checklist --input examples/valid-token.json --phase mainnet

Output:

════════════════════════════════════════════════════════
HIP-1 DEPLOYMENT CHECKLIST — MAINNET
════════════════════════════════════════════════════════

☐ [1] Prepare mainnet wallet
    Have a funded mainnet wallet with sufficient HYPE for deployment gas
    
    Action:
    Ensure wallet has: at least 1000 HYPE (500 floor + 100% buffer...)

☐ [2] Final parameter verification
    Double-check all token parameters against official Hyperliquid constraints
    
    Action:
    Token name: MEME
    weiDecimals: 8
    szDecimals: 3
    Verify: szDecimals + 5 = 8 ≤ weiDecimals = 8 ✅
    ...

Save reports to JSON

npm run cli -- validate --input examples/valid-token.json --output report.json
npm run cli -- checklist --input examples/valid-token.json --phase testnet --output checklist-testnet.json

Example input JSON format

See examples/ directory:

valid-token.json — Standard USDC-pair token (8,3)
high-precision.json — High-precision token (18,0)
invalid-constraint.json — Fails szDecimals + 5 ≤ weiDecimals constraint

MCP (Model Context Protocol) Server

The app exposes an MCP server at /mcp endpoint for integration with Claude and other AI tools. HTTP Streaming and Server-Sent Events (SSE) are both supported via Cloudflare Agents SDK.

Available Tools

validate_token_params — Validate HIP-1 token parameters against protocol constraints
estimate_budget — Calculate HYPE gas budget and USDC seed liquidity
generate_checklist — Generate testnet/mainnet deployment checklists
explain_constraint — Explain HIP-1/HIP-2 protocol rules and constraints

Usage (from AI clients)

MCP Server URL: https://hl-listing-calc.0xkaz.com/mcp
Transport: HTTP Streaming or SSE

Supported clients:

Claude (web, Claude Code, desktop app)
Cursor IDE
Any MCP-compatible client

Example (Claude)

@hl-listing-calc-mcp-server Call estimate_budget with:
- name: "MEME", weiDecimals: 8, szDecimals: 3
- maxSupply: "1000000000000000"
- startPx: "0.01", orderSz: "5000", nOrders: 20, nSeededLevels: 5

Test Suite

npm test                # Run unit tests with Vitest
npm run test:ui         # Interactive test browser UI
npm run e2e             # Run E2E tests with Playwright
npm run e2e:ui          # Interactive E2E test mode

# Test coverage includes:
# ✅ Valid token specs (USDC-like, high-precision)
# ❌ Invalid specs (constraint violations, bad parameters)
# ⚠️ Borderline cases (edge precision, seeding configs)
# 🖥️ E2E: UI interactions, form validation, live data updates

Key Constraints Enforced

Constraint	Rule	Validation
szDecimals + 5 ≤ weiDecimals	HIP-1 critical	❌ Error if violated
name ≤ 6 chars	HIP-1 spec	❌ Error if violated
weiDecimals ∈ [8, 76]	Hyperliquid impl	❌ Error if violated
maxSupply > 0	Basic validation	❌ Error if violated
USDC fixed to (8, 8)	HIP-1 spec	ℹ️ Info only

Testing

Comprehensive test fixtures:

✅ Valid: USDC-like (8,3), high-precision (18,0), 0 szDecimals
❌ Invalid: oversized name, constraint violation, negative values
⚠️ Borderline: edge cases for decimal precision
📊 HIP-2 Hyperliquidity: seeding config validation

npm test                # Run all tests
npm run test:ui         # Interactive test UI

Official References

Notes

All code and comments use English only
Refer to README.ja.md for Japanese documentation
Official Hyperliquid docs are the source of truth; confirm live before production use

Hyperliquid Hip 1 Deployment Calculator

At a glance

README