@basedone/core 0.0.1 → 0.0.6

package/lib/fee.ts

@@ -0,0 +1,105 @@
+// Global limits on Hyperliquid
+
+import { BASED_FEE_WALLET, BASED_REFERRAL_CODE } from "./constants/fee";
+
+// builder fee in 1/10 of a basis point
+const TARGET_SPOT_BUILDER_FEE = 100; // 0.1%
+const TARGET_FUTURES_BUILDER_FEE = 25; // 0.025%
+
+export const TARGET_APPROVED_MAX_BUILDER_FEE = Math.max(
+  TARGET_SPOT_BUILDER_FEE,
+  TARGET_FUTURES_BUILDER_FEE,
+); // 0.1%
+export const TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT = `0.1%`;
+
+/**
+ * Get the amount of builder fee to approve for
+ * @param perpetualTradingFee - Perp fee in percentage
+ * @param spotTradingFee - Spot fee in percentage
+ * @returns {
+ *   amount: number;  - The amount of builder fee to approve in 1/10 of a basis point
+ *   percent: string;  - eg. String input to approve fee, "0.1%"
+ * }
+ */
+export const getApprovalAmount = ({
+  customFeeEnabled,
+  perpetualTradingFee,
+  spotTradingFee,
+}: {
+  customFeeEnabled: boolean;
+  perpetualTradingFee?: number;
+  spotTradingFee?: number;
+}): {
+  approvalAmount: number;
+  approvalPercent: `${string}%`;
+  perpFee: number;
+  spotFee: number;
+  builder: `0x${string}`;
+  referralCode: string;
+} => {
+  if (!customFeeEnabled) {
+    return {
+      approvalAmount: TARGET_APPROVED_MAX_BUILDER_FEE,
+      perpFee: TARGET_FUTURES_BUILDER_FEE,
+      spotFee: TARGET_SPOT_BUILDER_FEE,
+      approvalPercent: TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT,
+      builder: BASED_FEE_WALLET,
+      referralCode: BASED_REFERRAL_CODE,
+    };
+  }
+  let validatedPerpFeePct = perpetualTradingFee;
+  if (validatedPerpFeePct === undefined) {
+    validatedPerpFeePct = TARGET_FUTURES_BUILDER_FEE / 1000;
+  }
+
+  // ensure perp fee is either 0 or between 0.01% and 0.1%
+  if (validatedPerpFeePct > 0 && validatedPerpFeePct < 0.01) {
+    console.warn("Perp fee is less than 0.01%, setting to 0.01%");
+    validatedPerpFeePct = 0.01;
+  }
+  if (validatedPerpFeePct < 0) {
+    console.warn("Perp fee is less than 0, setting to 0");
+    validatedPerpFeePct = 0;
+  }
+  if (validatedPerpFeePct > 0.1) {
+    console.warn("Perp fee is greater than 0.1%, setting to 0.1%");
+    validatedPerpFeePct = 0.1;
+  }
+
+  let validatedSpotFeePct = spotTradingFee;
+
+  if (validatedSpotFeePct === undefined) {
+    validatedSpotFeePct = TARGET_SPOT_BUILDER_FEE / 1000;
+  }
+  if (validatedSpotFeePct > 0 && validatedSpotFeePct < 0.025) {
+    console.warn("Spot fee is less than 0.025%, setting to 0.025%");
+    validatedSpotFeePct = 0.025;
+  }
+  if (validatedSpotFeePct < 0) {
+    console.warn("Spot fee is less than 0, setting to 0");
+    validatedSpotFeePct = 0;
+  }
+  if (validatedSpotFeePct > 1) {
+    console.warn("Spot fee is greater than 1%, setting to 1%");
+    validatedSpotFeePct = 1;
+  }
+
+  const perpFee = Math.floor(validatedPerpFeePct * 1000);
+  const spotFee = Math.floor(validatedSpotFeePct * 1000);
+
+  const requiredPercent =
+    validatedPerpFeePct > validatedSpotFeePct
+      ? validatedPerpFeePct
+      : validatedSpotFeePct;
+  const requiredAmount = Math.max(Math.floor(requiredPercent * 1000), 1); // 1/10 of a basis point (returned from Hyperliquid)
+  const requiredPercentString = `${requiredAmount / 1000}%`;
+
+  return {
+    approvalAmount: requiredAmount,
+    approvalPercent: requiredPercentString as `${string}%`,
+    perpFee: perpFee,
+    spotFee: spotFee,
+    builder: BASED_FEE_WALLET,
+    referralCode: BASED_REFERRAL_CODE,
+  };
+};

package/lib/hip3/market-info.ts

@@ -0,0 +1,25 @@
+// static HIP-3 market info
+
+import { SpotToken, PerpDex } from "@nktkas/hyperliquid";
+import { TESTNET_USDC_SPOT_TOKEN, USDC_SPOT_TOKEN } from "../constants/tokens";
+
+// currently /info type: perpDexs doesn't include collateral token
+interface HIP3DexInfo extends PerpDex {
+  collateralToken: SpotToken;
+}
+
+export const HIP3_DEX_INFO: Record<string, HIP3DexInfo> = {};
+
+const TESTNET_DEX_INFO: Record<string, HIP3DexInfo> = {
+  vtnls: {
+    collateralToken: TESTNET_USDC_SPOT_TOKEN,
+    name: "vntls",
+    full_name: "Ventuals",
+    deployer: "0xc65008a70f511ae0407d26022ff1516422acea94",
+    oracle_updater: null,
+  },
+};
+
+function getHIP3DexInfo(dex: string, isTestnet: boolean) {
+  return isTestnet ? TESTNET_DEX_INFO[dex] : HIP3_DEX_INFO[dex];
+}

package/lib/hip3/utils.ts

@@ -0,0 +1,9 @@
+export function isHip3Symbol(symbol: string) {
+  if (!symbol) return false;
+  return symbol.includes(":");
+}
+
+export function getHip3Dex(symbol: string) {
+  if (!symbol) return null;
+  return symbol.split(":")[0];
+}

package/lib/meta/README.md

@@ -0,0 +1,471 @@
+# MetadataClient
+
+A robust utility for handling Hyperliquid metadata and symbol-to-asset conversions for trading operations.
+
+## Features
+
+- ✅ **Type-safe symbol to asset ID conversion** for perps, spot, and HIP-3 markets
+- ✅ **Multi-quote asset support** (USDC, USDT0, USDH, etc.) - no hardcoded assumptions
+- ✅ **Correct asset ID calculation** per Hyperliquid spec
+- ✅ **Decimal precision information** for sizes and prices
+- ✅ **Market discovery** - find all trading pairs for a base token
+- ✅ **Case-insensitive lookups**
+- ✅ **Lazy initialization** support
+
+## Installation
+
+```bash
+pnpm add @basedone/core
+```
+
+## Quick Start
+
+### Mainnet (default)
+
+```typescript
+import { MetadataClient } from "@basedone/core";
+import { InfoClient, HttpTransport } from "@nktkas/hyperliquid";
+
+// Setup for mainnet
+const transport = new HttpTransport();
+const infoClient = new InfoClient({ transport });
+const metadata = new MetadataClient(infoClient);
+
+// Initialize (fetches metadata from Hyperliquid)
+await metadata.initialize();
+
+// Get market info for trading
+const btc = metadata.getPerpsMarket("BTC");
+console.log(btc);
+// {
+//   symbol: "BTC",
+//   assetId: 0,
+//   szDecimals: 5,
+//   type: "perps",
+//   maxLeverage: 40
+// }
+
+const purrUsdc = metadata.getSpotMarket("PURR", "USDC");
+console.log(purrUsdc);
+// {
+//   symbol: "PURR/USDC",
+//   assetId: 10000,
+//   szDecimals: 0,
+//   priceDecimals: 8,
+//   type: "spot",
+//   baseToken: "PURR",
+//   quoteToken: "USDC"
+// }
+```
+
+### Testnet
+
+```typescript
+// Setup for testnet
+const transport = new HttpTransport({
+  url: "https://api.hyperliquid-testnet.xyz/info"
+});
+const infoClient = new InfoClient({ transport });
+
+// Enable testnet mode
+const metadata = new MetadataClient(infoClient, {
+  isTestnet: true
+});
+
+await metadata.initialize();
+
+// Network info
+console.log(metadata.getNetworkInfo());
+// { isTestnet: true, useStaticFallback: true, initialized: true }
+```
+
+### Static Fallback (Offline Mode)
+
+The client includes bundled static metadata that's used as a fallback when API requests fail.
+
+```typescript
+// Enable static fallback (default: true)
+const metadata = new MetadataClient(infoClient, {
+  useStaticFallback: true  // Falls back to bundled data if API fails
+});
+
+// Or disable fallback (throws error if API fails)
+const metadata = new MetadataClient(infoClient, {
+  useStaticFallback: false
+});
+```
+
+## Asset ID Calculation
+
+The MetadataClient correctly calculates asset IDs according to Hyperliquid's spec:
+
+### Perpetuals
+```
+assetId = index in meta universe
+```
+Example: BTC is always index 0, so assetId = 0
+
+### Spot Markets
+```
+assetId = 10000 + index
+```
+Example: PURR/USDC at index 0 → assetId = 10000
+
+### HIP-3 (Builder Deployed Perps)
+```
+assetId = 100000 + (perp_dex_index * 10000) + index_in_meta
+```
+Example: vntls:ABC at dex index 1, market index 0 → assetId = 110000
+
+## API Reference
+
+### Constructor
+
+```typescript
+new MetadataClient(infoClient: InfoClient, config?: {
+  hip3Dexs?: string[];         // List of HIP-3 DEXs to load
+  lazyInit?: boolean;          // Auto-initialize on first use
+  isTestnet?: boolean;         // Use testnet (default: false)
+  useStaticFallback?: boolean; // Fallback to static data if API fails (default: true)
+})
+```
+
+### Core Methods
+
+#### `initialize(): Promise<void>`
+Fetches metadata from Hyperliquid. Call this once at startup.
+
+```typescript
+await metadata.initialize();
+```
+
+#### `getMarketBySymbol(symbol: string, quoteAsset?: string): Promise<MarketInfo | null>`
+Universal method to get market info. Handles perps, spot, and HIP-3 formats.
+
+```typescript
+// Perps
+const btc = await metadata.getMarketBySymbol("BTC");
+
+// Spot with default USDC quote
+const purr = await metadata.getMarketBySymbol("PURR/USDC");
+
+// Spot with custom quote
+const hype = await metadata.getMarketBySymbol("HYPE", "USDT0");
+
+// HIP-3
+const hip3 = await metadata.getMarketBySymbol("vntls:ABC");
+```
+
+#### `getPerpsMarket(symbol: string): MarketInfo | null`
+Get perpetuals market info.
+
+```typescript
+const eth = metadata.getPerpsMarket("ETH");
+// { symbol: "ETH", assetId: 1, szDecimals: 4, type: "perps", maxLeverage: 25 }
+```
+
+#### `getSpotMarket(baseSymbol: string, quoteSymbol?: string): MarketInfo | null`
+Get spot market info. Defaults to USDC quote if not specified.
+
+```typescript
+const purrUsdc = metadata.getSpotMarket("PURR", "USDC");
+const hypeUsdt = metadata.getSpotMarket("HYPE", "USDT0");
+```
+
+#### `getAllMarketsForBase(baseSymbol: string): MarketInfo[]`
+Get all trading pairs for a base token (useful for multi-quote scenarios).
+
+```typescript
+const hypeMarkets = metadata.getAllMarketsForBase("HYPE");
+// [
+//   { symbol: "HYPE/USDC", assetId: 10107, ... },
+//   { symbol: "HYPE/USDT0", assetId: 10207, ... },
+//   { symbol: "HYPE/USDH", assetId: 10232, ... }
+// ]
+```
+
+#### `getTokenInfo(tokenSymbol: string): TokenInfo | null`
+Get detailed token information.
+
+```typescript
+const usdc = metadata.getTokenInfo("USDC");
+// {
+//   name: "USDC",
+//   index: 0,
+//   szDecimals: 8,
+//   weiDecimals: 8,
+//   tokenId: "0x6d1e7cde53ba9467b783cb7c530ce054"
+// }
+```
+
+#### `getAvailableQuoteAssets(): string[]`
+Get all quote assets available in the system.
+
+```typescript
+const quotes = metadata.getAvailableQuoteAssets();
+// ["USDC", "USDT0", "USDH"]
+```
+
+#### `getNetworkInfo(): { isTestnet: boolean; useStaticFallback: boolean; initialized: boolean }`
+Get network configuration and initialization status.
+
+```typescript
+const info = metadata.getNetworkInfo();
+// {
+//   isTestnet: false,
+//   useStaticFallback: true,
+//   initialized: true
+// }
+```
+
+## Types
+
+### `MarketInfo`
+
+```typescript
+interface MarketInfo {
+  symbol: string;         // "BTC" or "PURR/USDC"
+  assetId: number;        // Trading asset ID
+  szDecimals: number;     // Size decimals for orders
+  type: "perps" | "spot" | "hip3";
+  maxLeverage?: number;   // For perps only
+
+  // Spot-specific
+  baseToken?: string;     // "PURR"
+  quoteToken?: string;    // "USDC"
+  priceDecimals?: number; // Price decimals (quote token's szDecimals)
+
+  // HIP-3 specific
+  dexName?: string;       // "vntls"
+  dexIndex?: number;      // DEX index
+}
+```
+
+### `TokenInfo`
+
+```typescript
+interface TokenInfo {
+  name: string;
+  index: number;
+  szDecimals: number;
+  weiDecimals: number;
+  tokenId: string;
+}
+```
+
+## Usage Examples
+
+### Trading Order Preparation
+
+```typescript
+// Get market info
+const market = await metadata.getMarketBySymbol("BTC");
+
+// Prepare order with correct decimals
+const order = {
+  asset: market.assetId,         // 0
+  size: "0.001",                 // Respects szDecimals (5 for BTC)
+  price: "50000.0",              // Max 5 sig figs, max 6-szDecimals decimals
+  isBuy: true,
+};
+```
+
+### Multi-Quote Asset Selection
+
+```typescript
+// Find all markets for HYPE
+const markets = metadata.getAllMarketsForBase("HYPE");
+
+// Show user all available quote options
+markets.forEach(m => {
+  console.log(`${m.baseToken}/${m.quoteToken} - Asset ID: ${m.assetId}`);
+});
+
+// User selects USDT0
+const selected = markets.find(m => m.quoteToken === "USDT0");
+```
+
+### Decimal Validation
+
+```typescript
+const market = metadata.getSpotMarket("PURR", "USDC");
+
+// Validate order size
+function validateSize(size: string, szDecimals: number): boolean {
+  const parts = size.split(".");
+  if (parts.length > 1) {
+    return parts[1].length <= szDecimals;
+  }
+  return true;
+}
+
+console.log(validateSize("1.001", market.szDecimals)); // false (szDecimals = 0)
+console.log(validateSize("1", market.szDecimals));     // true
+```
+
+### Price Decimal Rules
+
+Per Hyperliquid spec:
+- **Perps**: Max 5 significant figures, max `6 - szDecimals` decimal places
+- **Spot**: Max 5 significant figures, max `8 - szDecimals` decimal places
+- Integers always allowed regardless of sig figs
+
+```typescript
+const btc = metadata.getPerpsMarket("BTC"); // szDecimals = 5
+// Valid prices: 1234.5, 0.001234, 123456 (integer)
+// Invalid: 1234.56 (too many sig figs), 0.0012345 (> 6-5 = 1 decimal place)
+
+const purr = metadata.getSpotMarket("PURR"); // szDecimals = 0
+// Valid prices: 0.0001234 (8 decimal places max for spot)
+// Invalid: 0.00001234 (> 8-0 = 8 decimal places)
+```
+
+## Migration from SymbolMappingUtil
+
+### Before (SymbolMappingUtil)
+```typescript
+// ❌ Hardcoded USDC assumption
+const pair = `${token}/USDC`;
+const assetId = symbolMapping.getSpotAssetId(pair);
+
+// ❌ Error-prone with inconsistent usage
+symbolMapping.resolveSingleToken(token, "spot");
+```
+
+### After (MetadataClient)
+```typescript
+// ✅ Explicit quote asset handling
+const market = await metadata.getMarketBySymbol(token, quoteAsset);
+const assetId = market.assetId;
+
+// ✅ Type-safe, consistent API
+const allMarkets = metadata.getAllMarketsForBase(token);
+```
+
+## Best Practices
+
+1. **Initialize once at startup**
+   ```typescript
+   const metadata = new MetadataClient(infoClient);
+   await metadata.initialize();
+   ```
+
+2. **Configure network appropriately**
+   ```typescript
+   // For testnet
+   const metadata = new MetadataClient(testnetInfoClient, {
+     isTestnet: true,
+     useStaticFallback: true  // Recommended for reliability
+   });
+
+   // For production
+   const metadata = new MetadataClient(mainnetInfoClient, {
+     isTestnet: false,
+     useStaticFallback: true  // Fallback to static data if API unavailable
+   });
+   ```
+
+3. **Always specify quote asset for spot markets**
+   ```typescript
+   // Good
+   const market = metadata.getSpotMarket("HYPE", "USDC");
+
+   // Also acceptable (defaults to USDC)
+   const market = metadata.getSpotMarket("HYPE");
+   ```
+
+4. **Use getMarketBySymbol for user input**
+   ```typescript
+   // Handles both "BTC" (perps) and "PURR/USDC" (spot)
+   const market = await metadata.getMarketBySymbol(userInput);
+   ```
+
+5. **Cache metadata, not individual results**
+   ```typescript
+   // ✅ Good - metadata is cached
+   await metadata.initialize();
+
+   // ✅ Also good - lookups are fast in-memory
+   const btc1 = metadata.getPerpsMarket("BTC");
+   const btc2 = metadata.getPerpsMarket("BTC");
+   ```
+
+6. **Show all quote options to users**
+   ```typescript
+   const markets = metadata.getAllMarketsForBase(baseToken);
+   const quotes = metadata.getAvailableQuoteAssets();
+   ```
+
+7. **Handle initialization errors gracefully**
+   ```typescript
+   try {
+     await metadata.initialize();
+   } catch (error) {
+     // With useStaticFallback: true, this should rarely happen
+     // It means both API fetch AND static data loading failed
+     console.error("Failed to load metadata:", error);
+   }
+
+   // Check if initialized
+   const { initialized } = metadata.getNetworkInfo();
+   if (!initialized) {
+     console.error("Metadata not ready");
+   }
+   ```
+
+## Error Handling
+
+```typescript
+const market = await metadata.getMarketBySymbol("INVALID");
+if (!market) {
+  console.error("Market not found");
+  return;
+}
+
+// Type-safe access
+if (market.type === "spot") {
+  console.log(`Quote: ${market.quoteToken}`);
+} else if (market.type === "perps") {
+  console.log(`Leverage: ${market.maxLeverage}x`);
+}
+```
+
+## HIP-3 Support
+
+```typescript
+// Load HIP-3 DEX metadata
+const metadata = new MetadataClient(infoClient, {
+  hip3Dexs: ["vntls", "another-dex"]
+});
+await metadata.initialize();
+
+// Get HIP-3 market
+const hip3Market = metadata.getHip3Market("vntls:ABC");
+// {
+//   symbol: "vntls:ABC",
+//   assetId: 110000,  // 100000 + 1*10000 + 0
+//   szDecimals: 5,
+//   type: "hip3",
+//   dexName: "vntls",
+//   dexIndex: 1
+// }
+```
+
+## Testing
+
+The package includes comprehensive tests covering:
+- Perpetuals market lookups
+- Spot market lookups with multiple quotes
+- Asset ID calculations
+- Token information retrieval
+- Market discovery
+- Edge cases and error handling
+
+Run tests:
+```bash
+pnpm test
+```
+
+## License
+
+ISC