@mimicprotocol/lib-ts 0.0.1-rc.10

package/src/tokens/Token.ts

@@ -0,0 +1,169 @@
+import { environment } from '../environment'
+import { evm } from '../evm'
+import { NATIVE_ADDRESS } from '../helpers'
+import { Address, ChainId, EvmDecodeParam } from '../types'
+
+/**
+ * Represents a token on a blockchain network including data like symbol, decimals, and address.
+ * Supports both ERC-20 and native tokens.
+ */
+export class Token {
+  public static readonly EMPTY_DECIMALS: u8 = u8.MAX_VALUE
+  public static readonly EMPTY_SYMBOL: string = ''
+
+  private _symbol: string
+  private _address: Address
+  private _chainId: ChainId
+  private _decimals: u8
+  private _timestamp: Date | null = null
+
+  /**
+   * Creates a Token instance from an Address object.
+   * @param address - The contract address of the token
+   * @param chainId - The blockchain network identifier
+   * @param decimals - Number of decimal places (optional, will be queried if not provided)
+   * @param symbol - Token symbol (optional, will be queried if not provided)
+   * @param timestamp - Timestamp for historical queries (optional)
+   * @returns A new Token instance
+   */
+  static fromAddress(
+    address: Address,
+    chainId: ChainId,
+    decimals: u8 = Token.EMPTY_DECIMALS,
+    symbol: string = Token.EMPTY_SYMBOL,
+    timestamp: Date | null = null
+  ): Token {
+    return new Token(address, chainId, decimals, symbol, timestamp)
+  }
+
+  /**
+   * Creates a Token instance from a string address.
+   * @param address - The contract address as a hex string
+   * @param chainId - The blockchain network identifier
+   * @param decimals - Number of decimal places (optional, will be queried if not provided)
+   * @param symbol - Token symbol (optional, will be queried if not provided)
+   * @param timestamp - Timestamp for historical queries (optional)
+   * @returns A new Token instance
+   */
+  static fromString(
+    address: string,
+    chainId: ChainId,
+    decimals: u8 = Token.EMPTY_DECIMALS,
+    symbol: string = Token.EMPTY_SYMBOL,
+    timestamp: Date | null = null
+  ): Token {
+    return Token.fromAddress(Address.fromString(address), chainId, decimals, symbol, timestamp)
+  }
+
+  /**
+   * Creates a Token instance representing the native token of the specified chain.
+   * @param chainId - The blockchain network identifier
+   * @returns A new Token instance for the native token
+   */
+  static native(chainId: ChainId): Token {
+    switch (chainId) {
+      case ChainId.ETHEREUM:
+      case ChainId.BASE:
+      case ChainId.ARBITRUM:
+      case ChainId.OPTIMISM:
+        return Token.fromString(NATIVE_ADDRESS, chainId, 18, 'ETH')
+      case ChainId.GNOSIS:
+        return Token.fromString(NATIVE_ADDRESS, chainId, 18, 'xDAI')
+      default:
+        throw new Error(`Unsupported chainId: ${chainId}`)
+    }
+  }
+
+  /**
+   * Creates a new Token instance.
+   * @param address - The contract address of the token
+   * @param chainId - The blockchain network identifier
+   * @param decimals - Number of decimal places (optional, will be queried if not provided)
+   * @param symbol - Token symbol (optional, will be queried if not provided)
+   * @param timestamp - Timestamp for historical queries (optional)
+   */
+  constructor(
+    address: Address,
+    chainId: ChainId,
+    decimals: u8 = Token.EMPTY_DECIMALS,
+    symbol: string = Token.EMPTY_SYMBOL,
+    timestamp: Date | null = null
+  ) {
+    this._address = address
+    this._chainId = chainId
+    this._timestamp = timestamp
+    this._symbol = symbol
+    this._decimals = decimals
+    // Ensure symbol and decimals are set for native tokens.
+    // Since queries return only the address and chainId, missing metadata must be filled
+    // to prevent the symbol and decimals getters from failing for native tokens.
+    if (
+      this._address.equals(Address.fromString(NATIVE_ADDRESS)) &&
+      (this._symbol === Token.EMPTY_SYMBOL || this._decimals === Token.EMPTY_DECIMALS)
+    ) {
+      const nativeToken = Token.native(this._chainId)
+      if (this._symbol === Token.EMPTY_SYMBOL) {
+        this._symbol = nativeToken.symbol
+      }
+      if (this._decimals === Token.EMPTY_DECIMALS) {
+        this._decimals = nativeToken.decimals
+      }
+    }
+  }
+
+  get address(): Address {
+    return this._address.clone()
+  }
+
+  get chainId(): ChainId {
+    return this._chainId
+  }
+
+  get symbol(): string {
+    if (this._symbol === Token.EMPTY_SYMBOL) {
+      const response = environment.contractCall(this.address, this.chainId, this._timestamp, '0x95d89b41')
+      this._symbol = evm.decode(new EvmDecodeParam('string', response))
+    }
+    return this._symbol
+  }
+
+  get decimals(): u8 {
+    if (this._decimals == Token.EMPTY_DECIMALS) {
+      const result = environment.contractCall(this.address, this.chainId, this._timestamp, '0x313ce567')
+      this._decimals = u8.parse(evm.decode(new EvmDecodeParam('uint8', result)))
+    }
+    return this._decimals
+  }
+
+  set decimals(value: u8) {
+    this._decimals = value
+  }
+
+  set symbol(value: string) {
+    this._symbol = value
+  }
+
+  set timestamp(value: Date) {
+    this._timestamp = value
+  }
+
+  /**
+   * Checks if this token is equal to another token.
+   * Tokens are considered equal if they have the same address on the same chain.
+   * @param other - The token to compare with
+   * @returns True if both tokens represent the same asset
+   */
+  equals(other: Token): boolean {
+    const isSameChain = this.chainId === other.chainId
+    const isSameAddress = this.address.equals(other.address)
+    return isSameChain && isSameAddress
+  }
+
+  /**
+   * Tells the string representation of this token.
+   * @returns The token symbol
+   */
+  toString(): string {
+    return this.symbol
+  }
+}

package/src/tokens/TokenAmount.ts

@@ -0,0 +1,222 @@
+import { environment } from '../environment'
+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 {
+  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)
+  }
+
+  /**
+   * 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)
+  }
+
+  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 {
+    return new USD(amount)
+  }
+
+  /**
+   * Creates a new USD instance.
+   * @param amount - The amount in 18 decimals precision (must be non-negative)
+   */
+  constructor(amount: BigInt) {
+    if (amount.isNegative()) throw new Error('USD cannot be negative')
+    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)
+  }
+}