@0xmonaco/utils

Utility functions for the Monaco protocol. This package provides decimal conversion utilities and logging functionality.

Installation

npm install @0xmonaco/utils

Usage

Decimal Conversion

The package provides utilities for handling token amounts in different decimal formats:

import {
  convertToUniversal,
  convertFromUniversal,
  parseToUniversal,
  formatFromUniversal,
  UNIVERSAL_DECIMALS,
} from "@0xmonaco/utils";

// Convert between native decimals and universal 18-decimal format
const universalAmount = convertToUniversal(1000000n, 6); // 1 USDC (6 decimals) -> universal format
const nativeAmount = convertFromUniversal(universalAmount, 6); // universal format -> 1 USDC (6 decimals)

// Parse human-readable amounts directly to universal format
const universalAmount = parseToUniversal("1.5", 6); // "1.5" with 6 decimals -> universal format (bigint)

// Format universal amounts to human-readable strings
const readableAmount = formatFromUniversal(universalAmount, 6); // universal format -> "1.5" with 6 decimals

// Price conversion utilities
const universalPrice = convertToUniversalPrice(2000n, 6); // 2000 USDC (6 decimals) -> universal format
const nativePrice = convertFromUniversalPrice(universalPrice, 6); // universal format -> 2000 USDC (6 decimals)

Logging

A simple logging utility that provides consistent logging across the protocol:

import { createDefaultLogger, LogLevel } from "@0xmonaco/utils";

const logger = createDefaultLogger({
  level: "info" as LogLevel, // 'debug' | 'info' | 'warn' | 'error'
  debug: false, // enable/disable debug logs
});

logger.info("Order placed", { orderId: "0x123...", price: "2000", size: "1" });
logger.error("Order failed", {
  error: "Insufficient balance",
  orderId: "0x123...",
});
logger.debug("Market update", { bestBid: "1999", bestAsk: "2001" });
logger.warn("High slippage detected", { expected: "2000", actual: "2010" });

API Reference

Decimal Utilities

• UNIVERSAL_DECIMALS: The standard decimal format used by Monaco (18 decimals)
• convertToUniversal(amount: bigint, nativeDecimals: number): bigint
• convertFromUniversal(universalAmount: bigint, nativeDecimals: number): bigint
• convertToUniversalPrice(nativePrice: bigint, quoteDecimals: number): bigint
• convertFromUniversalPrice(universalPrice: bigint, quoteDecimals: number): bigint
• parseTokenAmount(amount: string, decimals: number): bigint
• formatTokenAmount(amount: bigint, decimals: number): string
• parseToUniversal(amount: string, nativeDecimals: number): bigint
• formatFromUniversal(universalAmount: bigint, nativeDecimals: number): string

Logging Utilities

• createDefaultLogger(options?: { level?: LogLevel; debug?: boolean }): Logger
  • level: 'debug' | 'info' | 'warn' | 'error' (default: 'info')
  • debug: boolean to enable/disable debug logs (default: false)