@basedone/core 0.0.1 → 0.0.7

package/dist/index.d.ts

@@ -1,2 +1,488 @@
-export * from "./lib/cloid";
-//# sourceMappingURL=index.d.ts.map
+import { SpotToken, PerpsMeta, PerpsAssetCtx, SpotMeta } from '@nktkas/hyperliquid';
+import { Hex } from '@nktkas/hyperliquid/script/src/types/mod';
+
+declare function encodeSlug(slug: string): bigint;
+declare function decodeSlug(value: bigint): string;
+declare function buildCloid(version: number, slug: string, clientId: number, oid: bigint | string, // bitint for oid, string for encoded string slug (12 characters max)
+options?: {
+    isMiniApp?: boolean;
+    miniAppTriggered?: boolean;
+    widgetType?: WidgetType | number;
+}): `0x${string}`;
+declare function parseCloid(cloidHex: `0x${string}`): {
+    prefix: string;
+    version: number;
+    slug: string;
+    clientId: number;
+    isMiniApp: boolean;
+    miniAppTriggered: boolean;
+    widgetTypeId: number;
+    oid: bigint;
+    decodedOid: string;
+    clientName: string;
+    widgetTypeName: string;
+} | null;
+type CloidData = ReturnType<typeof parseCloid>;
+declare function isBasedCloid(cloidHex?: `0x${string}` | null): boolean;
+declare function isTenantCloid(tenantTrackingSlug: string, cloidHex?: `0x${string}` | null): boolean;
+declare function isTrackingIdCloid(trackingId: bigint | string, cloidHex?: `0x${string}` | null): boolean;
+declare function normaliseSlug(slug: string): string;
+/**
+ * Normalise a tracking id to 12 characters
+ * @param trackingId - The tracking id to normalise
+ * @returns The normalised tracking id
+ */
+declare function normaliseTrackingId(trackingId: string): string;
+type ClientCode = string;
+declare const CloidClientCode: {
+    readonly Unset: 0;
+    readonly Web: 1;
+    readonly App: 2;
+    readonly TgBot: 3;
+    readonly TSL: 4;
+    readonly Grid: 5;
+    readonly Chase: 6;
+    readonly Desktop: 7;
+    readonly API: 8;
+};
+type ClientCodeType = keyof typeof CloidClientCode;
+type CloidClientCodeId = (typeof CloidClientCode)[ClientCodeType];
+declare const CloidClientCodeNameById: Record<number, ClientCodeType>;
+declare function getClientCodeNameById(id: number): string;
+declare const WidgetType: {
+    readonly Unset: 0;
+    readonly SidePanel: 1;
+    readonly Widget: 2;
+    readonly FloatingWidget: 3;
+};
+type WidgetType = keyof typeof WidgetType;
+type WidgetTypeId = (typeof WidgetType)[WidgetType];
+declare const WidgetTypeById: Record<number, WidgetType>;
+declare function getWidgetTypeById(id: number): string;
+/**
+ * @param tenantCode - The tenant code (max 5 characters, truncated if longer) default: "BASED"
+ * @param clientCode CloidClientCode - The client code (max 5 characters, truncated if longer) default: "Unset"
+ * @param oid - The oid (64 bits) used for identifying unique orders, default: 0xBA5ED10000BA5ED1 or string for encoded string slug (12 characters max)
+ * @param attribution - Mini-app and component options
+ * @returns The cloid
+ */
+declare function getCloid(tenantCode?: ClientCode | null, clientCode?: ClientCodeType | number, oid?: bigint | string, attribution?: {
+    isMiniApp?: boolean;
+    miniAppTriggered?: boolean;
+    widgetType?: WidgetType | number;
+}): `0x${string}`;
+declare function isClientCode(clientCode: ClientCodeType | number, cloidHex: `0x${string}`): boolean;
+declare function isWidgetType(widgetType: WidgetType | number, cloidHex: `0x${string}`): boolean;
+declare function isMiniAppCloid(cloidHex: `0x${string}`): boolean;
+declare function isMiniAppTriggeredCloid(cloidHex: `0x${string}`): boolean;
+
+declare const TARGET_APPROVED_MAX_BUILDER_FEE: number;
+declare 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%"
+ * }
+ */
+declare const getApprovalAmount: ({ customFeeEnabled, perpetualTradingFee, spotTradingFee, }: {
+    customFeeEnabled: boolean;
+    perpetualTradingFee?: number;
+    spotTradingFee?: number;
+}) => {
+    approvalAmount: number;
+    approvalPercent: `${string}%`;
+    perpFee: number;
+    spotFee: number;
+    builder: `0x${string}`;
+    referralCode: string;
+};
+
+/**
+ * PUP Token Eligibility Types and Constants
+ */
+interface V3LPTokenInfo {
+    token0: {
+        price: number;
+        value: number;
+        amount: number;
+        symbol: string;
+        address: string;
+    };
+    token1: {
+        price: number;
+        value: number;
+        amount: number;
+        symbol: string;
+        address: string;
+    };
+}
+interface UpheavalPosition {
+    pair: string;
+    pool: string;
+    value: number;
+    amount: string;
+    version: 'erc20' | 'v3' | 'v2';
+    v3LPTokenInfo?: V3LPTokenInfo;
+}
+interface UpheavalSnapshot {
+    id: string;
+    user_address: string;
+    total_lp_value: number;
+    position_count: number;
+    metadata: {
+        positions: UpheavalPosition[];
+        snapshot_date: string;
+    };
+    created_at: string;
+    userId: string | null;
+}
+interface UpheavalApiResponse {
+    success: boolean;
+    snapshot: {
+        timestamp: string;
+        user_count: number;
+    };
+    data: UpheavalSnapshot[];
+    cached_at: string;
+    filtered_by: string;
+}
+interface PupEligibilityResult {
+    isEligible: boolean;
+    boostPct: number;
+    isAirdropRecipient: boolean;
+    pupTokenAmount?: number;
+    totalLpValue?: number;
+    currentTier?: number;
+    currentBoost?: number;
+    nextTier?: number | null;
+    nextBoost?: number | null;
+    amountToNextTier?: number | null;
+    nextTierThreshold?: number | null;
+    progressPercentage?: number;
+}
+interface AirdropAllocationData {
+    amount: bigint | {
+        div: (divisor: number) => {
+            toNumber: () => number;
+        };
+    };
+    walletAddress: string;
+}
+declare const PUP_TOKEN_ADDRESS = "0x876e7f2f30935118a654fc0e1f807afc49efe500";
+declare const PUP_TOKEN_THRESHOLDS: {
+    readonly AIRDROP_70_PERCENT: 0.7;
+    readonly AIRDROP_35_PERCENT: 0.35;
+    readonly AIRDROP_110_PERCENT: 1.1;
+    readonly NON_AIRDROP_TOKENS: 2000000;
+};
+declare const XP_BOOST_PERCENTAGES: {
+    readonly NO_BOOST: 0;
+    readonly TIER_1: 25;
+    readonly TIER_2: 50;
+    readonly TIER_3: 60;
+};
+
+/**
+ * PUP Token Calculation Logic
+ * Pure functions for calculating PUP amounts and boost percentages
+ */
+
+/**
+ * Calculate total PUP amount from all positions
+ * @param positions Array of Upheaval positions
+ * @returns Total PUP token amount
+ */
+declare function calculateTotalPupAmount(positions: UpheavalPosition[]): number;
+/**
+ * Calculate XP boost percentage based on PUP holdings
+ * @param pupTokenAmount Current PUP token holdings
+ * @param normalizedAirDropAmount Normalized airdrop amount (divided by 1e18)
+ * @param isAirdropRecipient Whether user received an airdrop
+ * @returns Boost percentage (0, 25, 50, or 60)
+ */
+declare function calculateBoostPercentage(pupTokenAmount: number, normalizedAirDropAmount: number, isAirdropRecipient: boolean): number;
+/**
+ * Normalize airdrop amount from BigInt or Prisma Decimal
+ * @param amount Airdrop amount from database
+ * @returns Normalized amount as number
+ */
+declare function normalizeAirdropAmount(amount: bigint | {
+    div: (divisor: number) => {
+        toNumber: () => number;
+    };
+} | null | undefined): number;
+/**
+ * Get information about the next tier and amount needed to reach it
+ * @param pupTokenAmount Current PUP token holdings
+ * @param normalizedAirDropAmount Normalized airdrop amount (divided by 1e18)
+ * @param isAirdropRecipient Whether user received an airdrop
+ * @returns Information about current tier and progression to next tier
+ */
+declare function getNextTierInfo(pupTokenAmount: number, normalizedAirDropAmount: number, isAirdropRecipient: boolean): {
+    currentTier: number;
+    currentBoost: number;
+    nextTier: number | null;
+    nextBoost: number | null;
+    amountToNextTier: number | null;
+    nextTierThreshold: number | null;
+    progressPercentage: number;
+};
+
+declare const USDC_SPOT_TOKEN: SpotToken;
+declare const TESTNET_USDC_SPOT_TOKEN: SpotToken;
+
+interface PerpDex {
+    /** Short name of the perpetual dex. */
+    name: string;
+    /** Complete name of the perpetual dex. */
+    fullName: string;
+    /** Hex address of the dex deployer. */
+    deployer: Hex;
+    /** Hex address of the oracle updater, or null if not available. */
+    oracleUpdater: Hex | null;
+    feeRecipient: Hex | null;
+    assetToStreamingOiCap: [string, string][];
+}
+/**
+ * Market information for trading operations
+ */
+interface MarketInfo {
+    symbol: string;
+    assetId: number;
+    szDecimals: number;
+    type: "perps" | "spot" | "hip3";
+    coin: string;
+    displayName?: string;
+    imageUrl?: string;
+    maxLeverage?: number;
+    baseToken?: SpotToken;
+    quoteToken?: SpotToken;
+    dexName?: string;
+    dexIndex?: number;
+    dexDisplayName?: string;
+    dexImageUrl?: string;
+}
+interface DexInfo {
+    meta: PerpsMeta;
+    assetContext: PerpsAssetCtx[];
+    dexFullName: string;
+    dexName: string;
+    dexIndex: number;
+    collateralTokenSymbol: string;
+    displayName?: string;
+    imageUrl?: string;
+}
+type ExtendedPerpsMeta = PerpsMeta & {
+    collateralToken?: number;
+};
+/**
+ * Spot token information
+ */
+interface TokenInfo {
+    name: string;
+    index: number;
+    szDecimals: number;
+    weiDecimals: number;
+    tokenId: string;
+}
+/**
+ * Configuration for MetadataClient
+ */
+interface MetadataClientConfig {
+    /** List of HIP-3 DEX names to load metadata for */
+    hip3Dexs?: string[];
+    /** Whether to lazily initialize (fetch metadata on first use) */
+    lazyInit?: boolean;
+    /** Whether to use testnet (default: false for mainnet) */
+    isTestnet?: boolean;
+    /** Use static fallback data only, no API fetch */
+    onlyUseStaticFallback?: boolean;
+    /** Whether to use static fallback data if API fetch fails (default: true) */
+    useStaticFallback?: boolean;
+}
+/**
+ * MetadataClient - Handles Hyperliquid metadata for trading operations
+ *
+ * Provides a clean interface to:
+ * - Convert symbols to asset IDs and decimals
+ * - Handle spot markets with multiple quote assets (USDC, USDT0, USDH)
+ * - Support perpetuals and HIP-3 deployed DEXs
+ * - Calculate correct asset IDs per Hyperliquid spec
+ *
+ * Asset ID Calculation:
+ * - Perps: index in meta universe
+ * - Spot: 10000 + index
+ * - HIP-3: 100000 + perp_dex_index * 10000 + index_in_meta
+ */
+declare const ROOT_DEX = "hyperliquid";
+declare class MetadataClient {
+    private infoClient;
+    private config;
+    private isTestnet;
+    private spotMeta;
+    private perpsMeta;
+    private perpDexs;
+    private staticMeta;
+    private hip3DexsMeta;
+    private perpsSymbolToIndex;
+    private spotTokenNameToIndex;
+    private spotPairToMarket;
+    private baseTokenToMarkets;
+    private quoteAssets;
+    private coinToMarket;
+    private hip3SymbolToMarket;
+    private dexNameToIndex;
+    private initialized;
+    constructor(config?: MetadataClientConfig);
+    /**
+     * Initialize metadata by fetching from Hyperliquid
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load staticMeta.json for display overrides
+     * This is always loaded regardless of config.useStaticFallback
+     */
+    private loadStaticMetaOverrides;
+    /**
+     * Load static metadata from bundled JSON files
+     */
+    private loadStaticMetadata;
+    /**
+     * Build optimized lookup maps from raw metadata
+     * Called after metadata is loaded (from API or static files)
+     */
+    private buildLookupMaps;
+    /**
+     * Load metadata for a specific HIP-3 DEX
+     * Also builds optimized lookups for this DEX's markets
+     */
+    loadHip3Metadata(dexName: string): Promise<DexInfo>;
+    /**
+     * Build optimized lookups for HIP-3 markets of a specific DEX
+     */
+    private buildHip3MarketsForDex;
+    /**
+     * Ensure metadata is loaded (for lazy init)
+     */
+    private ensureInitialized;
+    /**
+     * Get market information by symbol
+     * Optimized: O(1) direct map lookup for most cases
+     * Lazily initialize hip-3 metadata if not already initialized
+     *
+     * @param symbol - Market symbol (e.g., "BTC", "PURR/USDC", "vntls:ABC")
+     * @param quoteAsset - Quote asset for spot markets (default: "USDC")
+     * @returns Market information or null if not found
+     */
+    getMarketBySymbolAsync(symbol: string, quoteAsset?: string): Promise<MarketInfo | null>;
+    getMarketByCoin(coin: string): MarketInfo | null;
+    /**
+     * Get perpetuals market information
+     * Optimized: O(1) map lookup instead of O(n) array search
+     */
+    getPerpsMarket(symbol: string): MarketInfo | null;
+    /**
+     * Get spot market information
+     * Optimized: O(1) map lookup instead of O(n) array searches
+     *
+     * @param baseSymbol - Base token symbol (e.g., "PURR", "UHYPE")
+     * @param quoteSymbol - Quote token symbol (default: "USDC")
+     */
+    getSpotMarket(baseSymbol: string, quoteSymbol?: string): MarketInfo | null;
+    /**
+     * Get HIP-3 market information
+     * Optimized: O(1) map lookup after DEX metadata is loaded
+     *
+     * @param symbol - HIP-3 market symbol (format: "dex:coin")
+     */
+    getHip3Market(symbol: string): Promise<MarketInfo | null>;
+    getHip3Dex(dexName: string): Promise<DexInfo | null>;
+    /**
+     * Get all available markets for a base token
+     * Optimized: O(1) map lookup instead of O(n) filter + map
+     * Useful for showing all quote asset options
+     */
+    getAllMarketsForBase(baseSymbol: string): MarketInfo[];
+    /**
+     * Get spot token information
+     * Optimized: O(1) map lookup instead of O(n) array search
+     */
+    getSpotTokenInfo(tokenSymbol: string): TokenInfo | null;
+    /**
+     * Get all available quote assets
+     * Optimized: O(1) pre-computed array instead of O(n) computation
+     */
+    getAvailableQuoteAssets(): string[];
+    /**
+     * Get raw metadata (for advanced use cases)
+     */
+    getRawMetadata(): {
+        spotMeta: SpotMeta | null;
+        perpsMeta: PerpsMeta | null;
+        perpDexs: (PerpDex | null)[];
+        hip3DexsMeta: {
+            [k: string]: DexInfo;
+        };
+    };
+    /**
+     * Get network configuration
+     */
+    getNetworkInfo(): {
+        isTestnet: boolean;
+        useStaticFallback: boolean | undefined;
+        initialized: boolean;
+    };
+}
+
+declare const formatPriceAndSize: ({ px, sz, szDecimals, isSpot, }: {
+    px: number;
+    sz: number;
+    szDecimals: number;
+    isSpot: boolean;
+}) => {
+    price: number;
+    size: number;
+};
+/**
+ * Formats price for order placement following Hyperliquid rules
+ * - Rounded to priceDecimals of the asset
+ * @param px - The price to format
+ * @param priceDecimals - Price decimals for the asset
+ * @returns Formatted price as number (rounded to priceDecimals if exceeds)
+ */
+declare const formatPriceForOrder: ({ px, szDecimals, isSpot, }: {
+    px: number;
+    szDecimals: number;
+    isSpot: boolean;
+}) => number;
+/**
+ * Formats size for order placement following Hyperliquid rules
+ * - Rounded to szDecimals of the asset
+ * @param sz - The size to format
+ * @param szDecimals - Size decimals for the asset
+ * @returns Formatted size as number (rounded down to szDecimals if exceeds)
+ */
+declare const formatSizeForOrder: ({ sz, szDecimals, }: {
+    sz: number;
+    szDecimals: number;
+}) => number;
+/**
+ * Get minimum price decimals for tick size calculations
+ * Uses the same logic as internal price formatting
+ *
+ * @param price - The current price
+ * @param szDecimals - Size decimals for the asset
+ * @param isSpot - Whether this is a spot market (true) or perp market (false)
+ * @returns Minimum decimal places for price display
+ *
+ * @example
+ * getPriceDecimals(1234.5, 0, false)    // 1 (PERP market)
+ * getPriceDecimals(0.00123, 0, true)    // 6 (SPOT market)
+ * getPriceDecimals(100000, 0, false)    // 0 (large prices)
+ */
+declare function getPriceDecimals(price: number, szDecimals: number, isSpot: boolean): number;
+
+export { type AirdropAllocationData, CloidClientCode, type CloidClientCodeId, CloidClientCodeNameById, type CloidData, type DexInfo, type ExtendedPerpsMeta, type MarketInfo, MetadataClient, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, type PerpDex, type PupEligibilityResult, ROOT_DEX, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, type TokenInfo, USDC_SPOT_TOKEN, type UpheavalApiResponse, type UpheavalPosition, type UpheavalSnapshot, type V3LPTokenInfo, WidgetType, WidgetTypeById, type WidgetTypeId, XP_BOOST_PERCENTAGES, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, decodeSlug, encodeSlug, formatPriceAndSize, formatPriceForOrder, formatSizeForOrder, getApprovalAmount, getClientCodeNameById, getCloid, getNextTierInfo, getPriceDecimals, getWidgetTypeById, isBasedCloid, isClientCode, isMiniAppCloid, isMiniAppTriggeredCloid, isTenantCloid, isTrackingIdCloid, isWidgetType, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid };