tempo.ts 0.0.6 → 0.1.0

package/src/viem/Tick.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, test } from 'vitest'
+import * as Tick from './Tick.js'
+
+describe('toPrice', () => {
+  test('converts tick 0 to price 1', () => {
+    expect(Tick.toPrice(0)).toBe('1')
+  })
+
+  test('converts positive ticks correctly', () => {
+    expect(Tick.toPrice(100)).toBe('1.001')
+    expect(Tick.toPrice(1000)).toBe('1.01')
+    expect(Tick.toPrice(2000)).toBe('1.02')
+  })
+
+  test('converts negative ticks correctly', () => {
+    expect(Tick.toPrice(-100)).toBe('0.999')
+    expect(Tick.toPrice(-1000)).toBe('0.99')
+    expect(Tick.toPrice(-2000)).toBe('0.98')
+  })
+
+  test('handles boundary values', () => {
+    expect(Tick.toPrice(Tick.minTick)).toBe('0.98')
+    expect(Tick.toPrice(Tick.maxTick)).toBe('1.02')
+  })
+
+  test('preserves exact 5 decimal precision', () => {
+    expect(Tick.toPrice(1)).toBe('1.00001')
+    expect(Tick.toPrice(-1)).toBe('0.99999')
+    expect(Tick.toPrice(1234)).toBe('1.01234')
+  })
+
+  test('throws error when tick is below minimum', () => {
+    expect(() => Tick.toPrice(-2001)).toThrow(Tick.TickOutOfBoundsError)
+    expect(() => Tick.toPrice(-2001)).toThrow('Tick -2001 is out of bounds.')
+    expect(() => Tick.toPrice(-3000)).toThrow(Tick.TickOutOfBoundsError)
+  })
+
+  test('throws error when tick is above maximum', () => {
+    expect(() => Tick.toPrice(2001)).toThrow(Tick.TickOutOfBoundsError)
+    expect(() => Tick.toPrice(2001)).toThrow('Tick 2001 is out of bounds.')
+    expect(() => Tick.toPrice(3000)).toThrow(Tick.TickOutOfBoundsError)
+  })
+
+  test('handles edge cases near bounds', () => {
+    expect(() => Tick.toPrice(-2000)).not.toThrow()
+    expect(() => Tick.toPrice(2000)).not.toThrow()
+  })
+})
+
+describe('fromPrice', () => {
+  test('converts price 1.0 to tick 0', () => {
+    expect(Tick.fromPrice('1.0')).toBe(0)
+    expect(Tick.fromPrice('1.00000')).toBe(0)
+  })
+
+  test('converts prices above 1.0 correctly', () => {
+    expect(Tick.fromPrice('1.001')).toBe(100)
+    expect(Tick.fromPrice('1.01')).toBe(1000)
+    expect(Tick.fromPrice('1.02')).toBe(2000)
+  })
+
+  test('converts prices below 1.0 correctly', () => {
+    expect(Tick.fromPrice('0.999')).toBe(-100)
+    expect(Tick.fromPrice('0.99')).toBe(-1000)
+    expect(Tick.fromPrice('0.98')).toBe(-2000)
+  })
+
+  test('handles boundary values', () => {
+    expect(Tick.fromPrice('0.98')).toBe(Tick.minTick)
+    expect(Tick.fromPrice('1.02')).toBe(Tick.maxTick)
+  })
+
+  test('handles different decimal precisions', () => {
+    expect(Tick.fromPrice('1.00001')).toBe(1)
+    expect(Tick.fromPrice('1.0001')).toBe(10)
+    expect(Tick.fromPrice('1.001')).toBe(100)
+    expect(Tick.fromPrice('0.99999')).toBe(-1)
+  })
+
+  test('truncates beyond 5 decimal places', () => {
+    // Should truncate, not round, extra decimals
+    expect(Tick.fromPrice('1.000019')).toBe(1) // Takes first 5: 1.00001
+    expect(Tick.fromPrice('1.000015')).toBe(1) // Takes first 5: 1.00001
+  })
+
+  test('validates string format', () => {
+    expect(() => Tick.fromPrice('abc')).toThrow(Tick.InvalidPriceFormatError)
+    expect(() => Tick.fromPrice('abc')).toThrow('Invalid price format')
+    expect(() => Tick.fromPrice('1.2.3')).toThrow(Tick.InvalidPriceFormatError)
+    expect(() => Tick.fromPrice('')).toThrow(Tick.InvalidPriceFormatError)
+  })
+
+  test('throws error when price results in tick below minimum', () => {
+    expect(() => Tick.fromPrice('0.979')).toThrow(Tick.PriceOutOfBoundsError)
+    expect(() => Tick.fromPrice('0.979')).toThrow(
+      'Price "0.979" results in tick -2100 which is out of bounds.',
+    )
+    expect(() => Tick.fromPrice('0.5')).toThrow(Tick.PriceOutOfBoundsError)
+  })
+
+  test('throws error when price results in tick above maximum', () => {
+    expect(() => Tick.fromPrice('1.021')).toThrow(Tick.PriceOutOfBoundsError)
+    expect(() => Tick.fromPrice('1.021')).toThrow(
+      'Price "1.021" results in tick 2100 which is out of bounds.',
+    )
+    expect(() => Tick.fromPrice('1.5')).toThrow(Tick.PriceOutOfBoundsError)
+  })
+
+  test('handles edge cases near bounds', () => {
+    expect(() => Tick.fromPrice('0.98')).not.toThrow()
+    expect(() => Tick.fromPrice('1.02')).not.toThrow()
+  })
+
+  test('handles whitespace', () => {
+    expect(Tick.fromPrice('  1.0  ')).toBe(0)
+    expect(Tick.fromPrice(' 1.001 ')).toBe(100)
+  })
+})
+
+describe('round-trip conversions', () => {
+  test('tick -> price -> tick preserves tick values exactly', () => {
+    const ticks = [-2000, -1000, -100, -1, 0, 1, 100, 1000, 2000]
+    for (const tick of ticks) {
+      const price = Tick.toPrice(tick)
+      const roundTripTick = Tick.fromPrice(price)
+      expect(roundTripTick).toBe(tick)
+    }
+  })
+
+  test('price -> tick -> price preserves price strings exactly', () => {
+    const prices = ['0.98', '0.99', '1', '1.01', '1.02']
+    for (const price of prices) {
+      const tick = Tick.fromPrice(price)
+      const roundTripPrice = Tick.toPrice(tick)
+      expect(roundTripPrice).toBe(price)
+    }
+  })
+
+  test('handles arbitrary precision in input strings', () => {
+    // Shorter decimal strings should round-trip correctly
+    expect(Tick.toPrice(Tick.fromPrice('1.0'))).toBe('1')
+    expect(Tick.toPrice(Tick.fromPrice('0.999'))).toBe('0.999')
+
+    // Longer decimal strings get truncated to 5 decimals
+    expect(Tick.toPrice(Tick.fromPrice('1.000019999'))).toBe('1.00001')
+  })
+})
+
+describe('error handling', () => {
+  test('InvalidPriceFormatError is catchable and has correct properties', () => {
+    try {
+      Tick.fromPrice('invalid')
+      expect.fail('Should have thrown')
+    } catch (error) {
+      expect(error).toBeInstanceOf(Tick.InvalidPriceFormatError)
+      expect(error).toHaveProperty('name', 'Tick.InvalidPriceFormatError')
+      expect((error as Error).message).toContain('Invalid price format')
+      expect((error as Error).message).toContain('invalid')
+      expect((error as Error).message).toContain(
+        'Price must be a decimal number string',
+      )
+    }
+  })
+
+  test('TickOutOfBoundsError is catchable and has correct properties', () => {
+    try {
+      Tick.toPrice(-2001)
+      expect.fail('Should have thrown')
+    } catch (error) {
+      expect(error).toBeInstanceOf(Tick.TickOutOfBoundsError)
+      expect(error).toHaveProperty('name', 'Tick.TickOutOfBoundsError')
+      // BaseError appends metaMessages to the message
+      expect((error as Error).message).toContain('Tick -2001 is out of bounds.')
+      expect((error as Error).message).toContain(
+        'Tick must be between -2000 and 2000.',
+      )
+    }
+  })
+
+  test('PriceOutOfBoundsError is catchable and has correct properties', () => {
+    try {
+      Tick.fromPrice('0.979')
+      expect.fail('Should have thrown')
+    } catch (error) {
+      expect(error).toBeInstanceOf(Tick.PriceOutOfBoundsError)
+      expect(error).toHaveProperty('name', 'Tick.PriceOutOfBoundsError')
+      expect((error as Error).message).toContain(
+        'Price "0.979" results in tick -2100 which is out of bounds.',
+      )
+      expect((error as Error).message).toContain(
+        'Tick must be between -2000 and 2000.',
+      )
+    }
+  })
+
+  test('can distinguish between error types', () => {
+    try {
+      Tick.fromPrice('invalid')
+    } catch (error) {
+      if (error instanceof Tick.InvalidPriceFormatError) {
+        expect(true).toBe(true) // Successfully caught as InvalidPriceFormatError
+      } else {
+        expect.fail('Should be InvalidPriceFormatError')
+      }
+    }
+
+    try {
+      Tick.toPrice(-2001)
+    } catch (error) {
+      if (error instanceof Tick.TickOutOfBoundsError) {
+        expect(true).toBe(true) // Successfully caught as TickOutOfBoundsError
+      } else {
+        expect.fail('Should be TickOutOfBoundsError')
+      }
+    }
+
+    try {
+      Tick.fromPrice('0.979')
+    } catch (error) {
+      if (error instanceof Tick.PriceOutOfBoundsError) {
+        expect(true).toBe(true) // Successfully caught as PriceOutOfBoundsError
+      } else {
+        expect.fail('Should be PriceOutOfBoundsError')
+      }
+    }
+  })
+})
+
+describe('precision and edge cases', () => {
+  test('handles very small price increments', () => {
+    // 0.1 bps = 0.001% = 0.00001 in decimal
+    expect(Tick.fromPrice('1.00001')).toBe(1)
+    expect(Tick.fromPrice('1.00002')).toBe(2)
+  })
+
+  test('price scale maintains exact 5 decimal precision', () => {
+    // The price scale is 100,000 which gives us exactly 5 decimal places
+    const price0 = Tick.toPrice(0)
+    const price1 = Tick.toPrice(1)
+    expect(price0).toBe('1')
+    expect(price1).toBe('1.00001')
+
+    // Verify exact difference
+    const diff = Number(price1) - Number(price0)
+    expect(diff).toBeCloseTo(0.00001, 10)
+  })
+
+  test('symmetric around 1.0', () => {
+    // +100 ticks should have same magnitude as -100 ticks from 1.0
+    const priceUp = Tick.toPrice(100)
+    const priceDown = Tick.toPrice(-100)
+    expect(priceUp).toBe('1.001')
+    expect(priceDown).toBe('0.999')
+
+    const upDiff = Number(priceUp) - 1.0
+    const downDiff = 1.0 - Number(priceDown)
+    expect(upDiff).toBeCloseTo(downDiff, 10)
+  })
+
+  test('validates 2% range', () => {
+    // At minimum tick, price should be exactly 2% below 1.0
+    const minPrice = Tick.toPrice(Tick.minTick)
+    expect(minPrice).toBe('0.98')
+    expect((1.0 - Number(minPrice)) / 1.0).toBeCloseTo(0.02, 10)
+
+    // At maximum tick, price should be exactly 2% above 1.0
+    const maxPrice = Tick.toPrice(Tick.maxTick)
+    expect(maxPrice).toBe('1.02')
+    expect((Number(maxPrice) - 1.0) / 1.0).toBeCloseTo(0.02, 10)
+  })
+
+  test('no floating point precision errors', () => {
+    // String-based parsing should eliminate float precision issues
+    expect(Tick.fromPrice('0.99999')).toBe(-1)
+    expect(Tick.fromPrice('1.00001')).toBe(1)
+
+    // These would potentially fail with float arithmetic
+    expect(Tick.fromPrice('0.98001')).toBe(-1999)
+    expect(Tick.fromPrice('1.01999')).toBe(1999)
+  })
+})

package/src/viem/Tick.ts

@@ -0,0 +1,176 @@
+import * as Errors from 'ox/Errors'
+
+/**
+ * Minimum allowed tick value.
+ */
+export const minTick = -2000
+
+/**
+ * Maximum allowed tick value.
+ */
+export const maxTick = 2000
+
+/**
+ * Price scaling factor (5 decimal places for 0.1 bps precision).
+ *
+ * @description
+ * The DEX uses a tick-based pricing system where:
+ * - Tick size: 0.1 bps (basis points)
+ * - Price range: ±2% from 1.0 (ticks from -2000 to +2000)
+ */
+export const priceScale = 100_000
+
+/**
+ * Converts a tick to a price string.
+ *
+ * @example
+ * ```ts
+ * import { Tick } from 'tempo.ts/viem'
+ *
+ * // Tick 0 = price of 1.0
+ * const price1 = Tick.toPrice(0) // "1"
+ *
+ * // Tick 100 = price of 1.001 (0.1% higher)
+ * const price2 = Tick.toPrice(100) // "1.001"
+ *
+ * // Tick -100 = price of 0.999 (0.1% lower)
+ * const price3 = Tick.toPrice(-100) // "0.999"
+ * ```
+ *
+ * @param tick - The tick value (range: -2000 to +2000).
+ * @returns The price as a string with exact decimal representation.
+ * @throws {TickOutOfBoundsError} If tick is out of bounds.
+ */
+export function toPrice(tick: toPrice.Tick): toPrice.ReturnType {
+  if (tick < minTick || tick > maxTick) {
+    throw new TickOutOfBoundsError({ tick })
+  }
+  // Use integer arithmetic to avoid floating point errors
+  const price = priceScale + tick
+  const whole = Math.floor(price / priceScale)
+
+  let decimal = (price % priceScale).toString().padStart(5, '0')
+  decimal = decimal.replace(/0+$/, '')
+
+  if (decimal.length === 0) return whole.toString()
+  return `${whole}.${decimal}`
+}
+
+export declare namespace toPrice {
+  export type Tick = number
+  export type ReturnType = string
+}
+
+/**
+ * Converts a price string to a tick.
+ *
+ * @example
+ * ```ts
+ * import { Tick } from 'tempo.ts/viem'
+ *
+ * // Price of 1.0 = tick 0
+ * const tick1 = Tick.fromPrice('1.0') // 0
+ * const tick2 = Tick.fromPrice('1.00000') // 0
+ *
+ * // Price of 1.001 = tick 100
+ * const tick3 = Tick.fromPrice('1.001') // 100
+ *
+ * // Price of 0.999 = tick -100
+ * const tick4 = Tick.fromPrice('0.999') // -100
+ * ```
+ *
+ * @param price - The price as a string (e.g., "1.001", "0.999").
+ * @returns The tick value.
+ * @throws {InvalidPriceTypeError} If the price is not a string.
+ * @throws {InvalidPriceFormatError} If the price format is invalid.
+ * @throws {PriceOutOfBoundsError} If the resulting tick is out of bounds.
+ */
+export function fromPrice(price: fromPrice.Price): fromPrice.ReturnType {
+  const priceStr = price.trim()
+  if (!/^-?\d+(\.\d+)?$/.test(priceStr))
+    throw new InvalidPriceFormatError({ price })
+
+  // Parse price using string manipulation to avoid float precision issues
+  const [w, d = '0'] = priceStr.split('.')
+  const whole = BigInt(w!)
+
+  // Pad or truncate decimal to exactly 5 digits
+  const decimal = BigInt(d.padEnd(5, '0').slice(0, 5))
+
+  // Calculate price
+  const priceInt = whole * BigInt(priceScale) + decimal
+
+  // Calculate tick
+  const tick = Number(priceInt - BigInt(priceScale))
+
+  if (tick < minTick || tick > maxTick)
+    throw new PriceOutOfBoundsError({ price, tick })
+
+  return tick
+}
+
+export declare namespace fromPrice {
+  export type Price = string
+  export type ReturnType = number
+}
+
+/**
+ * Error thrown when a tick value is out of the allowed bounds.
+ */
+export class TickOutOfBoundsError extends Errors.BaseError {
+  override readonly name = 'Tick.TickOutOfBoundsError'
+
+  constructor(options: TickOutOfBoundsError.Options) {
+    super(`Tick ${options.tick} is out of bounds.`, {
+      metaMessages: [`Tick must be between ${minTick} and ${maxTick}.`],
+    })
+  }
+}
+
+export declare namespace TickOutOfBoundsError {
+  export type Options = {
+    tick: number
+  }
+}
+
+/**
+ * Error thrown when a price string has an invalid format.
+ */
+export class InvalidPriceFormatError extends Errors.BaseError {
+  override readonly name = 'Tick.InvalidPriceFormatError'
+
+  constructor(options: InvalidPriceFormatError.Options) {
+    super(`Invalid price format: "${options.price}".`, {
+      metaMessages: ['Price must be a decimal number string (e.g., "1.001").'],
+    })
+  }
+}
+
+export declare namespace InvalidPriceFormatError {
+  export type Options = {
+    price: string
+  }
+}
+
+/**
+ * Error thrown when a price string results in an out-of-bounds tick.
+ */
+export class PriceOutOfBoundsError extends Errors.BaseError {
+  override readonly name = 'Tick.PriceOutOfBoundsError'
+
+  constructor(options: PriceOutOfBoundsError.Options) {
+    super(
+      `Price "${options.price}" results in tick ${options.tick} which is out of bounds.`,
+      {
+        metaMessages: [`Tick must be between ${minTick} and ${maxTick}.`],
+      },
+    )
+  }
+}
+
+export declare namespace PriceOutOfBoundsError {
+  export type Options = {
+    price: string
+    tick: number
+  }
+}

package/src/viem/TokenIds.ts

@@ -0,0 +1,2 @@
+export const defaultFeeToken = 1n
+export const defaultQuoteToken = 0n