@xyo-network/xl1-protocol 1.12.39 → 1.12.41

package/src/amount/Xl1Amount.ts

@@ -0,0 +1,113 @@
+/* eslint-disable @typescript-eslint/member-ordering */
+import { assertEx } from '@xylabs/assert'
+
+import {
+  AttoXL1, FemtoXL1, MicroXL1, MilliXL1, NanoXL1, PicoXL1, XL1Places,
+} from '../xl1/index.ts'
+import { ShiftedBigInt } from './ShiftedBigInt.ts'
+import type { ShiftedBigIntConfig } from './ShiftedBigIntConfig.ts'
+
+const MAX_XL1_AMOUNT = 2n ** 256n - 1n
+const allowedPlaces = Object.values(XL1Places)
+
+export interface XL1AmountInstance {
+  value: AttoXL1
+
+  to(places: bigint | number): bigint
+
+  milli: MilliXL1
+
+  micro: MicroXL1
+
+  nano: NanoXL1
+
+  pico: PicoXL1
+
+  femto: FemtoXL1
+
+  atto: AttoXL1
+
+  toString(places: number, config: Partial<ShiftedBigIntConfig>): string
+}
+
+export class XL1Amount implements XL1AmountInstance {
+  value: AttoXL1
+  private locale: Intl.LocalesArgument
+
+  constructor(value: bigint, locale: Intl.LocalesArgument = 'en-US') {
+    this.locale = locale
+    this.value = AttoXL1(value > MAX_XL1_AMOUNT ? MAX_XL1_AMOUNT : value < 0n ? 0n : value)
+  }
+
+  static from(value: bigint, places: bigint = XL1Places.atto) {
+    assertEx(allowedPlaces.includes(places), () => `Invalid conversion places (${places} not in ${allowedPlaces})`)
+    return new XL1Amount(value * 10n ** BigInt(places))
+  }
+
+  static fromMilli(value: MilliXL1) {
+    return this.from(value, XL1Places.milli)
+  }
+
+  static fromMicro(value: MicroXL1) {
+    return this.from(value, XL1Places.micro)
+  }
+
+  static fromNano(value: NanoXL1) {
+    return this.from(value, XL1Places.nano)
+  }
+
+  static fromPico(value: PicoXL1) {
+    return this.from(value, XL1Places.pico)
+  }
+
+  static fromFemto(value: FemtoXL1) {
+    return this.from(value, XL1Places.femto)
+  }
+
+  static fromAtto(value: AttoXL1) {
+    return this.from(value, XL1Places.atto)
+  }
+
+  to(places: number | bigint = XL1Places.atto) {
+    return this.value / 10n ** BigInt(places)
+  }
+
+  get milli() {
+    return MilliXL1(this.to(XL1Places.milli))
+  }
+
+  get micro() {
+    return MicroXL1(this.to(XL1Places.micro))
+  }
+
+  get nano() {
+    return NanoXL1(this.to(XL1Places.nano))
+  }
+
+  get pico() {
+    return PicoXL1(this.to(XL1Places.pico))
+  }
+
+  get femto() {
+    return FemtoXL1(this.to(XL1Places.femto))
+  }
+
+  get atto() {
+    return AttoXL1(this.to(XL1Places.atto))
+  }
+
+  toString(places: number = Number(XL1Places.atto), config: Partial<ShiftedBigIntConfig> = {}): string {
+    assertEx(allowedPlaces.includes(BigInt(places)), () => `Invalid conversion places (${places} not in ${allowedPlaces})`)
+    return new ShiftedBigInt(
+      this.value,
+      {
+        places,
+        locale: this.locale,
+        maxDecimal: places,
+        minDecimals: 0,
+        maxCharacters: places,
+        ...config,
+      },
+    ).toShortString()
+  }
+}

package/src/amount/index.ts

@@ -0,0 +1,4 @@
+export * from './ShiftedBigInt.ts'
+export * from './splitOnDecimal.ts'
+export * from './splitOnDecimalToString.ts'
+export * from './Xl1Amount.ts'

package/src/amount/specs/Xl1Amount.spec.ts

@@ -0,0 +1,166 @@
+import {
+  describe, expect, it,
+} from 'vitest'
+
+import type {
+  AttoXL1, FemtoXL1, MicroXL1, MilliXL1, NanoXL1, PicoXL1,
+} from '../../xl1/index.ts'
+import { XL1Places } from '../../xl1/index.ts'
+import { XL1Amount } from '../Xl1Amount.ts'
+
+describe('XL1Amount', () => {
+  describe('constructor', () => {
+    it('should create an instance with valid value', () => {
+      const amount = new XL1Amount(1000n)
+      expect(amount.value).toBe(1000n)
+    })
+
+    it('should clamp negative values to 0', () => {
+      const amount = new XL1Amount(-1000n)
+      expect(amount.value).toBe(0n)
+    })
+
+    // it('should clamp values exceeding MAX_XL1_AMOUNT', () => {
+    //   const maxValue = 2n ** 256n - 1n
+    //   const amount = new XL1Amount(maxValue + 1n)
+    //   expect(amount.value).toBe(maxValue)
+    // })
+
+    it('should accept custom locale', () => {
+      const amount = new XL1Amount(1000n, 'de-DE')
+      expect(amount.value).toBe(1000n)
+    })
+  })
+
+  describe('static from method', () => {
+    it('should create XL1Amount from value and places', () => {
+      const amount = XL1Amount.from(1n, XL1Places.milli)
+      expect(amount.value).toBe(1n * 10n ** XL1Places.milli)
+    })
+
+    it('should default to atto places', () => {
+      const amount = XL1Amount.from(1000n)
+      expect(amount.value).toBe(1000n)
+    })
+
+    it('should throw error for invalid places', () => {
+      expect(() => XL1Amount.from(1000n, 99n)).toThrow('Invalid conversion places')
+    })
+  })
+
+  describe('static factory methods', () => {
+    it('should create from milli', () => {
+      const amount = XL1Amount.fromMilli(1n as MilliXL1)
+      expect(amount.value).toBe(1n * 10n ** XL1Places.milli)
+    })
+
+    it('should create from micro', () => {
+      const amount = XL1Amount.fromMicro(1n as MicroXL1)
+      expect(amount.value).toBe(1n * 10n ** XL1Places.micro)
+    })
+
+    it('should create from nano', () => {
+      const amount = XL1Amount.fromNano(1n as NanoXL1)
+      expect(amount.value).toBe(1n * 10n ** XL1Places.nano)
+    })
+
+    it('should create from pico', () => {
+      const amount = XL1Amount.fromPico(1n as PicoXL1)
+      expect(amount.value).toBe(1n * 10n ** XL1Places.pico)
+    })
+
+    it('should create from femto', () => {
+      const amount = XL1Amount.fromFemto(1n as FemtoXL1)
+      expect(amount.value).toBe(1n * 10n ** XL1Places.femto)
+    })
+
+    it('should create from atto', () => {
+      const amount = XL1Amount.fromAtto(1000n as AttoXL1)
+      expect(amount.value).toBe(1000n)
+    })
+  })
+
+  describe('to method', () => {
+    it('should convert to specified places', () => {
+      const amount = new XL1Amount(1_000_000_000_000_000_000n) // 1 * 10^18
+      expect(amount.to(XL1Places.milli)).toBe(1000n)
+    })
+
+    it('should default to atto places', () => {
+      const amount = new XL1Amount(1000n)
+      expect(amount.to()).toBe(1000n)
+    })
+
+    it('should handle bigint places', () => {
+      const amount = new XL1Amount(1_000_000_000_000_000_000n)
+      expect(amount.to(XL1Places.milli)).toBe(1000n)
+    })
+  })
+
+  describe('getters', () => {
+    const oneXl1 = 1n * 10n ** BigInt(XL1Places.xl1) // 1 * 10^18
+    const amount = new XL1Amount(oneXl1) // 1 * 10^18
+
+    it('should get milli value', () => {
+      expect(amount.milli).toBe(1000n)
+    })
+
+    it('should get micro value', () => {
+      expect(amount.micro).toBe(1_000_000n)
+    })
+
+    it('should get nano value', () => {
+      expect(amount.nano).toBe(1_000_000_000n)
+    })
+
+    it('should get pico value', () => {
+      expect(amount.pico).toBe(1_000_000_000_000n)
+    })
+
+    it('should get femto value', () => {
+      expect(amount.femto).toBe(1_000_000_000_000_000n)
+    })
+
+    it('should get atto value', () => {
+      expect(amount.atto).toBe(oneXl1)
+    })
+  })
+
+  describe('toString method', () => {
+    it('should convert to string with default places', () => {
+      const amount = new XL1Amount(1_000_000_000_000_000_000n)
+      const result = amount.toString()
+      expect(typeof result).toBe('string')
+    })
+
+    it('should convert to string with specified places', () => {
+      const amount = new XL1Amount(1_000_000_000_000_000_000n)
+      const result = amount.toString(Number(XL1Places.milli))
+      expect(typeof result).toBe('string')
+    })
+
+    it('should accept custom config', () => {
+      const amount = new XL1Amount(1_000_000_000_000_000_000n)
+      const result = amount.toString(Number(XL1Places.milli), { minDecimals: 2 })
+      expect(typeof result).toBe('string')
+    })
+
+    it('should throw error for invalid places', () => {
+      const amount = new XL1Amount(1000n)
+      expect(() => amount.toString(99)).toThrow('Invalid conversion places')
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle zero value', () => {
+      const amount = new XL1Amount(0n)
+      expect(amount.value).toBe(0n)
+      expect(amount.to(XL1Places.milli)).toBe(0n)
+    })
+
+    it('should handle division with remainder', () => {
+      const amount = new XL1Amount(1_500_000_000_000_000_000n)
+      expect(amount.to(XL1Places.milli)).toBe(1500n)
+    })
+  })
+})

package/src/amount/splitOnDecimal.ts

@@ -0,0 +1,5 @@
+export const splitOnDecimal = (value: bigint, places = 18): [bigint, bigint] => {
+  const whole = value / BigInt(10 ** places)
+  const decimal = value % BigInt(10 ** places)
+  return [whole, decimal]
+}

package/src/amount/splitOnDecimalToString.ts

@@ -0,0 +1,37 @@
+import { splitOnDecimal } from './splitOnDecimal.ts'
+
+export const splitOnDecimalToString = (
+  value: bigint,
+  places = 18,
+  maxDecimal = places,
+  maxCharacters = 9,
+  minDecimals = 1,
+  locale: Intl.LocalesArgument = 'en-US',
+): string => {
+  const [whole, decimal] = splitOnDecimal(value, places)
+  if (whole === 0n && decimal < 10 ** maxDecimal && decimal !== 0n) return '< 0.'.padEnd(maxDecimal + 5, '0') + '1'
+
+  const wholeCharacters = whole.toString(10).length
+  const calcMaxDecimalCharacters = maxCharacters === -1 ? places : wholeCharacters > maxCharacters ? 0 : maxCharacters - wholeCharacters
+  const maxDecimalCharacters = Math.min(maxDecimal, calcMaxDecimalCharacters)
+
+  // Format whole number with thousand separators according to locale
+  const formattedWhole = new Intl.NumberFormat(locale, {
+    maximumFractionDigits: 0,
+    useGrouping: true,
+  }).format(whole)
+
+  // Get decimal separator for the locale
+  const decimalSeparator = new Intl.NumberFormat(locale)
+    .formatToParts(1.1)
+    .find(part => part.type === 'decimal')?.value ?? '.'
+
+  // Pad decimal part to correct number of places
+  let paddedDecimal = decimal.toString().padStart(places, '0').slice(0, maxDecimalCharacters)
+  // remove unneeded trailing zeros (honoring minDecimals)
+  while (paddedDecimal.length > minDecimals && paddedDecimal.endsWith('0')) {
+    paddedDecimal = paddedDecimal.slice(0, -1)
+  }
+
+  return `${formattedWhole}${paddedDecimal.length > 0 ? decimalSeparator : ''}${paddedDecimal}`
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from './amount/index.ts'
 export * from './block/index.ts'
 export * from './chain/index.ts'
 export * from './constants/index.ts'

package/src/interfaces/view/AccountBalance.ts

@@ -7,8 +7,8 @@ import type { AttoXL1 } from '../../xl1/index.ts'
 export type AccountBalanceHistoryItem = [Hash /* block */, Hash /* transaction */, Transfer /* the actual transfer payload */]
 
 export interface AccountBalancesViewInterface {
-  accountBalanceHistories(address: Address): Promisable<Partial<Record<Address, AccountBalanceHistoryItem[]>>>
   accountBalances(address: Address[]): Promisable<Partial<Record<Address, AttoXL1>>>
+  accountBalancesHistories(address: Address[]): Promisable<Partial<Record<Address, AccountBalanceHistoryItem[]>>>
 }
 
 export interface AccountBalanceViewInterface {

package/src/interfaces/view/TransferBalance.ts

@@ -0,0 +1,22 @@
+import type { Address, Hash } from '@xylabs/hex'
+import type { Promisable } from '@xylabs/promise'
+
+import type { Transfer } from '../../payload/index.ts'
+import type { AttoXL1 } from '../../xl1/index.ts'
+
+export type TransferBalanceHistoryItem = [Hash /* block */, Hash /* transaction */, Transfer /* the actual transfer payload */]
+export type TransferPair = [/* from */ Address, /* to */Address]
+
+export interface TransferBalancesViewInterface {
+  transferBalances(address: Address[]): Promisable<Partial<Record<Address, Record<Address, AttoXL1>>>>
+  transferBalancesHistories(address: Address[]): Promisable<Partial<Record<Address, Record<Address, TransferBalanceHistoryItem[]>>>>
+  transferPairBalances(address: TransferPair[]): Promisable<Partial<Record<Address, Record<Address, AttoXL1>>>>
+  transferPairBalancesHistories(address: TransferPair[]): Promisable<Partial<Record<Address, Record<Address, TransferBalanceHistoryItem[]>>>>
+}
+
+export interface TransferBalanceViewInterface {
+  transferBalance(address: Address): Promisable<AttoXL1>
+  transferBalanceHistory(address: Address): Promisable<TransferBalanceHistoryItem[]>
+  transferPairBalance(address: TransferPair): Promisable<AttoXL1>
+  transferPairBalanceHistory(address: TransferPair): Promisable<TransferBalanceHistoryItem[]>
+}

package/src/interfaces/view/index.ts

@@ -10,3 +10,4 @@ export * from './StakeTotals.ts'
 export * from './StepStake.ts'
 export * from './TimeSync.ts'
 export * from './Transaction.ts'
+export * from './TransferBalance.ts'

package/src/provider/XyoViewer.ts

@@ -2,8 +2,8 @@ import type {
   AccountBalanceViewInterface, BlockViewInterface, ChainViewInterface,
   ForkViewInterface,
   StakeViewInterface,
-  TransactionViewInterface,
+  TransactionViewInterface, TransferBalanceViewInterface,
 } from '../interfaces/index.ts'
 
-export interface XyoViewer extends AccountBalanceViewInterface,
+export interface XyoViewer extends AccountBalanceViewInterface, TransferBalanceViewInterface,
   ChainViewInterface, BlockViewInterface, TransactionViewInterface, StakeViewInterface, ForkViewInterface {}

package/src/services/StakeIntentService/ChainIndexingServiceStateSchema.ts

@@ -36,8 +36,8 @@ export const isChainIndexingServiceState = <T extends JsonValue = JsonValue>(pay
 export const asChainIndexingServiceState = AsObjectFactory.create<ChainIndexingServiceState<JsonValue>>(isChainIndexingServiceState)
 
 export const isChainIndexingServiceStateWithStorageMeta
-= <T extends JsonValue = JsonValue>(value: unknown): value is WithStorageMeta<ChainIndexingServiceState<T>> =>
-  isChainIndexingServiceState<T>(value) && isStorageMeta(value)
+  = <T extends JsonValue = JsonValue>(value: unknown): value is WithStorageMeta<ChainIndexingServiceState<T>> =>
+    isChainIndexingServiceState<T>(value) && isStorageMeta(value)
 
 export const asChainIndexingServiceStateWithStorageMeta
-= AsObjectFactory.create<WithStorageMeta<ChainIndexingServiceState>>(isChainIndexingServiceStateWithStorageMeta)
+  = AsObjectFactory.create<WithStorageMeta<ChainIndexingServiceState>>(isChainIndexingServiceStateWithStorageMeta)