@mimicprotocol/lib-ts 0.0.1-rc.9

package/src/tokens/TokenAmount.ts

@@ -0,0 +1,248 @@
+import { environment } from '../environment'
+import { join, parseCSV, Serializable, serialize } from '../helpers'
+import { BigInt } from '../types'
+
+import { Token } from './Token'
+import { USD } from './USD'
+
+/**
+ * Represents an amount of a specific token, combining the token metadata with a quantity.
+ * Supports arithmetic operations, comparisons, and conversions between tokens and USD.
+ */
+export class TokenAmount implements Serializable {
+  private static readonly SERIALIZED_PREFIX: string = 'TokenAmount'
+
+  private _token: Token
+  private _amount: BigInt
+
+  /**
+   * Creates a TokenAmount from a decimal string representation.
+   * @param token - The token to create an amount for
+   * @param amount - The amount as a decimal string (e.g., "1.5", "100.0")
+   * @returns A new TokenAmount instance
+   */
+  static fromStringDecimal(token: Token, amount: string): TokenAmount {
+    return this.fromBigInt(token, BigInt.fromStringDecimal(amount, token.decimals))
+  }
+
+  /**
+   * Creates a TokenAmount from a 32-bit integer.
+   * @param token - The token to create an amount for
+   * @param amount - The amount as a whole number (will be scaled by token decimals)
+   * @returns A new TokenAmount instance
+   */
+  static fromI32(token: Token, amount: i32): TokenAmount {
+    return this.fromBigInt(token, BigInt.fromI32(amount).upscale(token.decimals))
+  }
+
+  /**
+   * Creates a TokenAmount from a BigInt amount.
+   * @param token - The token to create an amount for
+   * @param amount - The amount in the token's smallest unit (e.g., wei for ETH)
+   * @returns A new TokenAmount instance
+   */
+  static fromBigInt(token: Token, amount: BigInt): TokenAmount {
+    return new TokenAmount(token, amount)
+  }
+
+  /**
+   * Parses a serialized TokenAmount string and creates a TokenAmount instance.
+   * @param serialized - The serialized string in format: TokenAmount(token,amount)
+   * @returns A new TokenAmount instance parsed from the serialized data
+   */
+  static parse(serialized: string): TokenAmount {
+    const isTokenAmount = serialized.startsWith(`${TokenAmount.SERIALIZED_PREFIX}(`) && serialized.endsWith(')')
+    if (!isTokenAmount) throw new Error('Invalid serialized token amount')
+
+    const elements = parseCSV(serialized.slice(TokenAmount.SERIALIZED_PREFIX.length + 1, -1))
+    const areNull = elements.some((element) => element === null)
+    if (areNull) throw new Error('Invalid serialized token amount')
+
+    const token = Token.parse(elements[0]!)
+    const amount = BigInt.parse(elements[1]!)
+
+    return new TokenAmount(token, amount)
+  }
+
+  /**
+   * Creates a new TokenAmount instance.
+   * @param token - The token this amount represents
+   * @param amount - The amount in the token's smallest unit (must be non-negative)
+   */
+  constructor(token: Token, amount: BigInt) {
+    if (amount.isNegative()) throw new Error('Token amount cannot be negative')
+    this._token = token
+    this._amount = amount.clone()
+  }
+
+  get token(): Token {
+    return this._token
+  }
+
+  get amount(): BigInt {
+    return this._amount.clone()
+  }
+
+  get symbol(): string {
+    return this.token.symbol
+  }
+
+  get decimals(): u8 {
+    return this.token.decimals
+  }
+
+  /**
+   * Checks if this token amount is zero.
+   * @returns True if the amount is zero
+   */
+  isZero(): boolean {
+    return this.amount.isZero()
+  }
+
+  /**
+   * Adds another TokenAmount to this one.
+   * @param other - The TokenAmount to add (must be the same token)
+   * @returns A new TokenAmount representing the sum
+   */
+  @operator('+')
+  plus(other: TokenAmount): TokenAmount {
+    this.checkToken(other.token, 'add')
+    return TokenAmount.fromBigInt(this.token, this.amount.plus(other.amount))
+  }
+
+  /**
+   * Subtracts another TokenAmount from this one.
+   * @param other - The TokenAmount to subtract (must be the same token)
+   * @returns A new TokenAmount representing the difference
+   */
+  @operator('-')
+  minus(other: TokenAmount): TokenAmount {
+    this.checkToken(other.token, 'subtract')
+    return TokenAmount.fromBigInt(this.token, this.amount.minus(other.amount))
+  }
+
+  /**
+   * Multiplies this TokenAmount by a BigInt factor.
+   * @param other - The BigInt to multiply by
+   * @returns A new TokenAmount representing the product
+   */
+  @operator('*')
+  times(other: BigInt): TokenAmount {
+    return TokenAmount.fromBigInt(this.token, this.amount.times(other))
+  }
+
+  /**
+   * Divides this TokenAmount by a BigInt divisor.
+   * @param other - The BigInt to divide by (cannot be zero)
+   * @returns A new TokenAmount representing the quotient
+   */
+  @operator('/')
+  div(other: BigInt): TokenAmount {
+    return TokenAmount.fromBigInt(this.token, this.amount.div(other))
+  }
+
+  /**
+   * Checks if this TokenAmount is less than another.
+   * @param other - The TokenAmount to compare with (must be the same token)
+   * @returns True if this amount is smaller
+   */
+  @operator('<')
+  lt(other: TokenAmount): boolean {
+    this.checkToken(other.token, 'lt')
+    return this.amountCompare(other) < 0
+  }
+
+  /**
+   * Checks if this TokenAmount is greater than another.
+   * @param other - The TokenAmount to compare with (must be the same token)
+   * @returns True if this amount is larger
+   */
+  @operator('>')
+  gt(other: TokenAmount): boolean {
+    this.checkToken(other.token, 'gt')
+    return this.amountCompare(other) > 0
+  }
+
+  /**
+   * Checks if this TokenAmount is less than or equal to another.
+   * @param other - The TokenAmount to compare with (must be the same token)
+   * @returns True if this amount is smaller or equal
+   */
+  @operator('<=')
+  le(other: TokenAmount): boolean {
+    this.checkToken(other.token, 'le')
+    return this.amountCompare(other) <= 0
+  }
+
+  /**
+   * Checks if this TokenAmount is greater than or equal to another.
+   * @param other - The TokenAmount to compare with (must be the same token)
+   * @returns True if this amount is larger or equal
+   */
+  @operator('>=')
+  ge(other: TokenAmount): boolean {
+    this.checkToken(other.token, 'ge')
+    return this.amountCompare(other) >= 0
+  }
+
+  /**
+   * Checks if this TokenAmount is equal to another.
+   * @param other - The TokenAmount to compare with
+   * @returns True if both represent the same token and amount
+   */
+  @operator('==')
+  equals(other: TokenAmount): boolean {
+    return this.token.equals(other.token) && this.amountCompare(other) === 0
+  }
+
+  /**
+   * Checks if this TokenAmount is not equal to another.
+   * @param other - The TokenAmount to compare with
+   * @returns True if they represent different tokens or amounts
+   */
+  @operator('!=')
+  notEquals(other: TokenAmount): boolean {
+    return !this.token.equals(other.token) || this.amountCompare(other) !== 0
+  }
+
+  /**
+   * Tells the string representation of this TokenAmount.
+   * @returns Formatted string showing the decimal amount and symbol (e.g., "1.5 ETH")
+   */
+  toString(): string {
+    return `${this.amount.toStringDecimal(this.decimals)} ${this.token.symbol}`
+  }
+
+  /**
+   * Converts this TokenAmount to its USD equivalent.
+   * @returns A USD instance representing the current USD value
+   */
+  toUsd(): USD {
+    if (this.isZero()) return USD.zero()
+    const tokenPrice = environment.getPrice(this.token)
+    const amountUsd = this.amount.times(tokenPrice.value).downscale(this.decimals)
+    return USD.fromBigInt(amountUsd)
+  }
+
+  /**
+   * Converts this TokenAmount to an equivalent amount of another token.
+   * @param other - The target token to convert to
+   * @returns A TokenAmount of the target token with equivalent USD value
+   */
+  toTokenAmount(other: Token): TokenAmount {
+    if (this.isZero()) return TokenAmount.fromI32(other, 0)
+    return this.toUsd().toTokenAmount(other)
+  }
+
+  serialize(): string {
+    return `${TokenAmount.SERIALIZED_PREFIX}(${join([serialize(this.token), serialize(this.amount)])})`
+  }
+
+  private amountCompare(other: TokenAmount): i32 {
+    return BigInt.compare(this._amount, other.amount)
+  }
+
+  private checkToken(other: Token, action: string): void {
+    if (!this.token.equals(other)) throw new Error(`Cannot ${action} different tokens`)
+  }
+}

package/src/tokens/USD.ts

@@ -0,0 +1,201 @@
+import { environment } from '../environment'
+import { STANDARD_DECIMALS } from '../helpers'
+import { Token, TokenAmount } from '../tokens'
+import { BigInt } from '../types'
+
+/**
+ * Represents a USD amount with fixed decimal precision.
+ * Supports arithmetic operations, comparisons, and conversions to token amounts.
+ */
+export class USD {
+  private _value: BigInt
+
+  /**
+   * Creates a USD instance representing zero dollars.
+   * @returns A new USD instance with value 0
+   */
+  static zero(): USD {
+    return new USD(BigInt.zero())
+  }
+
+  /**
+   * Creates a USD instance from a decimal string representation.
+   * @param amount - The amount as a decimal string (e.g., "1.50", "100.00")
+   * @returns A new USD instance
+   */
+  static fromStringDecimal(amount: string): USD {
+    return USD.fromBigInt(BigInt.fromStringDecimal(amount, STANDARD_DECIMALS))
+  }
+
+  /**
+   * Creates a USD instance from a 32-bit integer.
+   * @param amount - The amount as a whole number (e.g., 150 for $150.00)
+   * @returns A new USD instance
+   */
+  static fromI32(amount: i32): USD {
+    return USD.fromBigInt(BigInt.fromI32(amount).upscale(STANDARD_DECIMALS))
+  }
+
+  /**
+   * Creates a USD instance from a BigInt amount.
+   * @param amount - The amount in 18 decimals precision (must be non-negative)
+   * @returns A new USD instance
+   */
+  static fromBigInt(amount: BigInt): USD {
+    if (amount.isNegative()) throw new Error('USD cannot be negative')
+    return new USD(amount)
+  }
+
+  /**
+   * Creates a new USD instance.
+   * @param amount - The amount in 18 decimals precision (must be non-negative)
+   */
+  constructor(amount: BigInt) {
+    this._value = amount.clone()
+  }
+
+  /**
+   * Tells the value of this USD amount in 18 decimals precision.
+   * @returns A new BigInt instance representing the value
+   */
+  get value(): BigInt {
+    return this._value.clone()
+  }
+
+  /**
+   * Checks if this USD amount is zero.
+   * @returns True if the amount is zero
+   */
+  isZero(): boolean {
+    return this.value.isZero()
+  }
+
+  /**
+   * Adds another USD amount to this one.
+   * @param other - The USD amount to add
+   * @returns A new USD instance representing the sum
+   */
+  @operator('+')
+  plus(other: USD): USD {
+    return USD.fromBigInt(this.value.plus(other.value))
+  }
+
+  /**
+   * Subtracts another USD amount from this one.
+   * @param other - The USD amount to subtract
+   * @returns A new USD instance representing the difference
+   */
+  @operator('-')
+  minus(other: USD): USD {
+    return USD.fromBigInt(this.value.minus(other.value))
+  }
+
+  /**
+   * Multiplies this USD amount by a BigInt factor.
+   * @param other - The BigInt to multiply by
+   * @returns A new USD instance representing the product
+   */
+  @operator('*')
+  times(other: BigInt): USD {
+    return USD.fromBigInt(this.value.times(other))
+  }
+
+  /**
+   * Divides this USD amount by a BigInt divisor.
+   * @param other - The BigInt to divide by (cannot be zero)
+   * @returns A new USD instance representing the quotient
+   */
+  @operator('/')
+  div(other: BigInt): USD {
+    return USD.fromBigInt(this.value.div(other))
+  }
+
+  /**
+   * Checks if this USD amount is equal to another.
+   * @param other - The USD amount to compare with
+   * @returns True if both amounts are equal
+   */
+  @operator('==')
+  equals(other: USD): boolean {
+    return this.compare(other) === 0
+  }
+
+  /**
+   * Checks if this USD amount is not equal to another.
+   * @param other - The USD amount to compare with
+   * @returns True if the amounts are different
+   */
+  @operator('!=')
+  notEquals(other: USD): boolean {
+    return this.compare(other) !== 0
+  }
+
+  /**
+   * Checks if this USD amount is less than another.
+   * @param other - The USD amount to compare with
+   * @returns True if this amount is smaller
+   */
+  @operator('<')
+  lt(other: USD): boolean {
+    return this.compare(other) < 0
+  }
+
+  /**
+   * Checks if this USD amount is greater than another.
+   * @param other - The USD amount to compare with
+   * @returns True if this amount is larger
+   */
+  @operator('>')
+  gt(other: USD): boolean {
+    return this.compare(other) > 0
+  }
+
+  /**
+   * Checks if this USD amount is less than or equal to another.
+   * @param other - The USD amount to compare with
+   * @returns True if this amount is smaller or equal
+   */
+  @operator('<=')
+  le(other: USD): boolean {
+    return this.compare(other) <= 0
+  }
+
+  /**
+   * Checks if this USD amount is greater than or equal to another.
+   * @param other - The USD amount to compare with
+   * @returns True if this amount is larger or equal
+   */
+  @operator('>=')
+  ge(other: USD): boolean {
+    return this.compare(other) >= 0
+  }
+
+  /**
+   * Compares this USD amount with another.
+   * @param other - The USD amount to compare with
+   * @returns -1 if smaller, 0 if equal, 1 if larger
+   */
+  compare(other: USD): i32 {
+    return BigInt.compare(this._value, other.value)
+  }
+
+  /**
+   * Tells the string representation of this USD amount.
+   * @returns Decimal string representation (e.g., "1.50", "100")
+   */
+  toString(): string {
+    return this._value.toStringDecimal(STANDARD_DECIMALS)
+  }
+
+  /**
+   * Converts this USD amount to an equivalent token amount.
+   * @param token - The target token to convert to
+   * @returns A TokenAmount representing the equivalent value in the target token
+   */
+  toTokenAmount(token: Token): TokenAmount {
+    if (this.isZero()) return TokenAmount.fromI32(token, 0)
+    const tokenPrice = environment.getPrice(token)
+    const tokenAmount = this.value.upscale(token.decimals).div(tokenPrice.value)
+    return TokenAmount.fromBigInt(token, tokenAmount)
+  }
+}

package/src/tokens/index.ts

@@ -0,0 +1,3 @@
+export * from './Token'
+export * from './TokenAmount'
+export * from './USD'

package/src/types/Address.ts

@@ -0,0 +1,60 @@
+// eslint-disable-next-line no-secrets/no-secrets
+// This file is based on code from "The Graph Tooling" (https://github.com/graphprotocol/graph-tooling/tree/7faa3098b2e6c61f09fc81b8b2d333e66b0080d1).
+// Licensed under the MIT License.
+// Copyright (c) 2018 Graph Protocol, Inc. and contributors.
+// Modified by Mimic Protocol, 2025.
+
+import { ByteArray } from './ByteArray'
+import { Bytes } from './Bytes'
+
+/**
+ * Represents an Ethereum address, a fixed-length 20-byte value.
+ */
+export class Address extends Bytes {
+  /**
+   * Returns a zero address (20 bytes filled with zeroes).
+   */
+  static zero(): Address {
+    const self = new ByteArray(20)
+    return changetype<Address>(self)
+  }
+
+  /**
+   * Converts a string representation of an address to an Address instance.
+   * It is assumed that the string is a hex string.
+   */
+  static fromString(str: string): Address {
+    return this.fromHexString(str)
+  }
+
+  /**
+   * Converts a hex string representation of an address to an Address instance.
+   */
+  static fromHexString(str: string): Address {
+    const bytes = Bytes.fromHexString(str)
+    return this.fromBytes(bytes)
+  }
+
+  /**
+   * Converts a Bytes instance to an Address.
+   * Throws an error if the input is not exactly 20 bytes long.
+   */
+  static fromBytes(bytes: Bytes): Address {
+    if (bytes.length != 20) throw new Error(`Bytes of length ${bytes.length} can not be converted to 20 byte addresses`)
+    return changetype<Address>(bytes)
+  }
+
+  /**
+   * Returns the address in hexadecimal. This method is overridden to avoid
+   * returning the UTF-8 encoded version of the address.
+   */
+  toString(): string {
+    return super.toHexString()
+  }
+
+  clone(): Address {
+    const copy = new ByteArray(this.length)
+    copy.set(this)
+    return changetype<Address>(copy)
+  }
+}