@mimicprotocol/lib-ts 0.0.1-rc.10

package/src/intents/Transfer.ts

@@ -0,0 +1,349 @@
+import { environment } from '../environment'
+import { Token, TokenAmount } from '../tokens'
+import { Address, BigInt, ChainId } from '../types'
+
+import { Intent, IntentBuilder, OperationType } from './Intent'
+
+/**
+ * Builder for creating Transfer intents with token transfer operations.
+ * Supports multiple transfers within a single transaction on the same chain.
+ */
+export class TransferBuilder extends IntentBuilder {
+  private chainId: ChainId
+  private transfers: TransferData[] = []
+  private fee: TokenAmount | null = null
+
+  /**
+   * Creates a TransferBuilder for a specific chain.
+   * @param chainId - The blockchain network identifier
+   * @returns A new TransferBuilder instance
+   */
+  static forChain(chainId: ChainId): TransferBuilder {
+    return new TransferBuilder(chainId)
+  }
+
+  /**
+   * Creates a TransferBuilder for a specific chain with a pre-configured fee.
+   * @param chainId - The blockchain network identifier
+   * @param fee - The fee token amount for the transfer
+   * @returns A new TransferBuilder instance with fee set
+   */
+  static forChainWithFee(chainId: ChainId, fee: TokenAmount): TransferBuilder {
+    const builder = new TransferBuilder(chainId)
+    builder.addFee(fee)
+    return builder
+  }
+
+  /**
+   * Creates a new TransferBuilder instance.
+   * @param chainId - The blockchain network identifier
+   */
+  constructor(chainId: ChainId) {
+    super()
+    this.chainId = chainId
+  }
+
+  /**
+   * Adds a transfer to the intent.
+   * @param transfer - The transfer data configuration
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransfer(transfer: TransferData): TransferBuilder {
+    this.transfers.push(transfer)
+    return this
+  }
+
+  /**
+   * Adds multiple transfers to the intent.
+   * @param transfers - Array of transfer data configurations
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransfers(transfers: TransferData[]): TransferBuilder {
+    for (let i = 0; i < transfers.length; i++) this.transfers.push(transfers[i])
+    return this
+  }
+
+  /**
+   * Adds a transfer from a TokenAmount.
+   * @param tokenAmount - The token amount to transfer (must be on same chain)
+   * @param recipient - The address to receive the tokens
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransferFromTokenAmount(tokenAmount: TokenAmount, recipient: Address): TransferBuilder {
+    if (tokenAmount.token.chainId !== this.chainId) throw new Error('Transfer tokens must be on the same chain')
+    return this.addTransfer(TransferData.fromTokenAmount(tokenAmount, recipient))
+  }
+
+  /**
+   * Adds a transfer from a 32-bit integer amount.
+   * @param token - The token to transfer (must be on same chain)
+   * @param amount - The amount as a whole number
+   * @param recipient - The address to receive the tokens
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransferFromI32(token: Token, amount: i32, recipient: Address): TransferBuilder {
+    if (token.chainId !== this.chainId) throw new Error('Transfer tokens must be on the same chain')
+    return this.addTransfer(TransferData.fromI32(token, amount, recipient))
+  }
+
+  /**
+   * Adds a transfer from a BigInt amount.
+   * @param token - The token to transfer (must be on same chain)
+   * @param amount - The amount in the token's smallest unit
+   * @param recipient - The address to receive the tokens
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransferFromBigInt(token: Token, amount: BigInt, recipient: Address): TransferBuilder {
+    if (token.chainId !== this.chainId) throw new Error('Transfer tokens must be on the same chain')
+    return this.addTransfer(TransferData.fromBigInt(token, amount, recipient))
+  }
+
+  /**
+   * Adds a transfer from a decimal string amount.
+   * @param token - The token to transfer (must be on same chain)
+   * @param amount - The amount as a decimal string
+   * @param recipient - The address to receive the tokens
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransferFromStringDecimal(token: Token, amount: string, recipient: Address): TransferBuilder {
+    if (token.chainId !== this.chainId) throw new Error('Transfer tokens must be on the same chain')
+    return this.addTransfer(TransferData.fromStringDecimal(token, amount, recipient))
+  }
+
+  /**
+   * Adds multiple transfers from TokenAmounts to the same recipient.
+   * @param tokenAmounts - Array of token amounts to transfer (must be on same chain)
+   * @param recipient - The address to receive all the tokens
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addTransfersFromTokenAmounts(tokenAmounts: TokenAmount[], recipient: Address): TransferBuilder {
+    for (let i = 0; i < tokenAmounts.length; i++) this.addTransferFromTokenAmount(tokenAmounts[i], recipient)
+    return this
+  }
+
+  /**
+   * Sets the fee for this transfer intent.
+   * @param fee - The fee token amount (must be on same chain)
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addFee(fee: TokenAmount): TransferBuilder {
+    if (fee.token.chainId !== this.chainId) throw new Error('Fee token must be on the same chain')
+    this.fee = fee
+    return this
+  }
+
+  /**
+   * Sets the settler address for this intent.
+   * @param settler - The settler address as an Address instance
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addSettler(settler: Address): TransferBuilder {
+    return changetype<TransferBuilder>(super.addSettler(settler))
+  }
+
+  /**
+   * Sets the settler address from a string.
+   * @param settler - The settler address as a hex string
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addSettlerAsString(settler: string): TransferBuilder {
+    return changetype<TransferBuilder>(super.addSettlerAsString(settler))
+  }
+
+  /**
+   * Sets the deadline for this intent.
+   * @param deadline - The deadline as a timestamp
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addDeadline(deadline: BigInt): TransferBuilder {
+    return changetype<TransferBuilder>(super.addDeadline(deadline))
+  }
+
+  /**
+   * Sets the user address for this intent.
+   * @param user - The user address
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addUser(user: Address): TransferBuilder {
+    return changetype<TransferBuilder>(super.addUser(user))
+  }
+
+  /**
+   * Sets the user address from a string.
+   * @param user - The user address as a hex string
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addUserAsString(user: string): TransferBuilder {
+    return changetype<TransferBuilder>(super.addUserAsString(user))
+  }
+
+  /**
+   * Sets the nonce for this intent.
+   * @param nonce - A unique identifier to prevent replay attacks
+   * @returns This TransferBuilder instance for method chaining
+   */
+  addNonce(nonce: string): TransferBuilder {
+    return changetype<TransferBuilder>(super.addNonce(nonce))
+  }
+
+  /**
+   * Builds and returns the final Transfer intent.
+   * @returns A new Transfer instance with all configured parameters
+   */
+  build(): Transfer {
+    if (!this.fee) throw new Error('Transfer fee must be specified')
+    return new Transfer(
+      this.chainId,
+      this.transfers,
+      this.fee as TokenAmount,
+      this.settler,
+      this.user,
+      this.deadline,
+      this.nonce
+    )
+  }
+}
+
+/**
+ * Represents transfer data for a single token transfer operation.
+ * Specifies the token, amount, and recipient for the transfer.
+ */
+@json
+export class TransferData {
+  public token: string
+  public amount: string
+  public recipient: string
+
+  /**
+   * Creates TransferData from a TokenAmount.
+   * @param tokenAmount - The token amount to transfer
+   * @param recipient - The address to receive the tokens
+   * @returns A new TransferData instance
+   */
+  static fromTokenAmount(tokenAmount: TokenAmount, recipient: Address): TransferData {
+    return new TransferData(tokenAmount.token.address, tokenAmount.amount, recipient)
+  }
+
+  /**
+   * Creates TransferData from a 32-bit integer amount.
+   * @param token - The token to transfer
+   * @param amount - The amount as a whole number
+   * @param recipient - The address to receive the tokens
+   * @returns A new TransferData instance
+   */
+  static fromI32(token: Token, amount: i32, recipient: Address): TransferData {
+    return this.fromTokenAmount(TokenAmount.fromI32(token, amount), recipient)
+  }
+
+  /**
+   * Creates TransferData from a BigInt amount.
+   * @param token - The token to transfer
+   * @param amount - The amount in the token's smallest unit
+   * @param recipient - The address to receive the tokens
+   * @returns A new TransferData instance
+   */
+  static fromBigInt(token: Token, amount: BigInt, recipient: Address): TransferData {
+    return this.fromTokenAmount(TokenAmount.fromBigInt(token, amount), recipient)
+  }
+
+  /**
+   * Creates TransferData from a decimal string amount.
+   * @param token - The token to transfer
+   * @param amount - The amount as a decimal string
+   * @param recipient - The address to receive the tokens
+   * @returns A new TransferData instance
+   */
+  static fromStringDecimal(token: Token, amount: string, recipient: Address): TransferData {
+    return this.fromTokenAmount(TokenAmount.fromStringDecimal(token, amount), recipient)
+  }
+
+  /**
+   * Creates a new TransferData instance.
+   * @param token - The token address
+   * @param amount - The amount in the token's smallest unit
+   * @param recipient - The address to receive the tokens
+   */
+  constructor(token: Address, amount: BigInt, recipient: Address) {
+    this.token = token.toString()
+    this.amount = amount.toString()
+    this.recipient = recipient.toString()
+  }
+}
+
+/**
+ * Represents a Transfer intent for sending tokens to recipients on a blockchain network.
+ */
+@json
+export class Transfer extends Intent {
+  public chainId: ChainId
+  public transfers: TransferData[]
+  public feeToken: string
+  public feeAmount: string
+
+  /**
+   * Creates a simple single-token transfer intent.
+   * @param chainId - The blockchain network identifier
+   * @param token - The token address to transfer
+   * @param amount - The amount to transfer
+   * @param recipient - The address to receive the tokens
+   * @param fee - The fee amount for the transfer
+   * @param settler - The settler address (optional)
+   * @param user - The user address (optional)
+   * @param deadline - The deadline timestamp (optional)
+   * @param nonce - The nonce for replay protection (optional)
+   * @returns A new Transfer instance
+   */
+  static create(
+    chainId: ChainId,
+    token: Address,
+    amount: BigInt,
+    recipient: Address,
+    fee: BigInt,
+    settler: Address | null = null,
+    user: Address | null = null,
+    deadline: BigInt | null = null,
+    nonce: string | null = null
+  ): Transfer {
+    const transferToken = Token.fromAddress(token, chainId)
+    const transferAmount = TokenAmount.fromBigInt(transferToken, amount)
+    const transferData = TransferData.fromTokenAmount(transferAmount, recipient)
+    const feeAmount = TokenAmount.fromBigInt(transferToken, fee)
+    return new Transfer(chainId, [transferData], feeAmount, settler, user, deadline, nonce)
+  }
+
+  /**
+   * Creates a new Transfer intent.
+   * @param chainId - The blockchain network identifier
+   * @param transfers - Array of transfer data configurations
+   * @param fee - The fee token amount for the transfers
+   * @param settler - The settler address (optional)
+   * @param user - The user address (optional)
+   * @param deadline - The deadline timestamp (optional)
+   * @param nonce - The nonce for replay protection (optional)
+   */
+  constructor(
+    chainId: ChainId,
+    transfers: TransferData[],
+    fee: TokenAmount,
+    settler: Address | null = null,
+    user: Address | null = null,
+    deadline: BigInt | null = null,
+    nonce: string | null = null
+  ) {
+    super(OperationType.Transfer, chainId, settler, user, deadline, nonce)
+
+    if (transfers.length === 0) throw new Error('Transfer list cannot be empty')
+
+    this.transfers = transfers
+    this.feeToken = fee.token.address.toString()
+    this.feeAmount = fee.amount.toString()
+    this.chainId = chainId
+  }
+
+  /**
+   * Sends this Transfer intent to the execution environment.
+   */
+  send(): void {
+    environment.transfer(this)
+  }
+}

package/src/intents/index.ts

@@ -0,0 +1,4 @@
+export * from './Call'
+export * from './Intent'
+export * from './Swap'
+export * from './Transfer'

package/src/log.ts

@@ -0,0 +1,83 @@
+// 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.
+
+export namespace log {
+  @external('log', '_log')
+  declare function _log(level: Level, msg: string): void
+
+  export enum Level {
+    CRITICAL = 0,
+    ERROR = 1,
+    WARNING = 2,
+    INFO = 3,
+    DEBUG = 4,
+  }
+
+  /**
+   * Logs a critical message that terminates the execution.
+   *
+   * @param msg Format string like "Value = {}, other = {}".
+   * @param args Format string arguments.
+   */
+  export function critical(msg: string, args: Array<string> = []): void {
+    _log(Level.CRITICAL, format(msg, args))
+  }
+
+  /**
+   * Logs an error message.
+   *
+   * @param msg Format string like "Value = {}, other = {}".
+   * @param args Format string arguments.
+   */
+  export function error(msg: string, args: Array<string> = []): void {
+    _log(Level.ERROR, format(msg, args))
+  }
+
+  /** Logs a warning message.
+   *
+   * @param msg Format string like "Value = {}, other = {}".
+   * @param args Format string arguments.
+   */
+  export function warning(msg: string, args: Array<string> = []): void {
+    _log(Level.WARNING, format(msg, args))
+  }
+
+  /** Logs an info message.
+   *
+   * @param msg Format string like "Value = {}, other = {}".
+   * @param args Format string arguments.
+   */
+  export function info(msg: string, args: Array<string> = []): void {
+    _log(Level.INFO, format(msg, args))
+  }
+
+  /** Logs a debug message.
+   *
+   * @param msg Format string like "Value = {}, other = {}".
+   * @param args Format string arguments.
+   */
+  export function debug(msg: string, args: Array<string> = []): void {
+    _log(Level.DEBUG, format(msg, args))
+  }
+}
+
+function format(fmt: string, args: string[]): string {
+  let out = ''
+  let argIndex = 0
+  for (let i: i32 = 0, len: i32 = fmt.length; i < len; i++) {
+    if (i < len - 1 && fmt.charCodeAt(i) == 0x7b /* '{' */ && fmt.charCodeAt(i + 1) == 0x7d /* '}' */) {
+      if (argIndex >= args.length) {
+        throw new Error('Too few arguments for format string: ' + fmt)
+      } else {
+        out += args[argIndex++]
+        i++
+      }
+    } else {
+      out += fmt.charAt(i)
+    }
+  }
+  return out
+}

package/src/queries/Call.ts

@@ -0,0 +1,27 @@
+import { Address, ChainId } from '../types'
+
+@json
+class CallBase {
+  constructor(
+    public readonly to: string,
+    public readonly chainId: ChainId,
+    public readonly data: string
+  ) {}
+}
+
+@json
+export class Call extends CallBase {
+  public readonly timestamp: i64
+
+  constructor(to: string, chainId: ChainId, timestamp: i64, data: string) {
+    super(to, chainId, data)
+    this.timestamp = timestamp
+  }
+
+  static from(to: Address, chainId: ChainId, timestamp: Date | null, data: string): CallBase {
+    const address = to.toString()
+    return timestamp
+      ? new Call(address, chainId, changetype<Date>(timestamp).getTime(), data)
+      : new CallBase(address, chainId, data)
+  }
+}

package/src/queries/GetPrice.ts

@@ -0,0 +1,28 @@
+import { Token } from '../tokens'
+
+@json
+class GetPriceBase {
+  constructor(
+    public readonly address: string,
+    public readonly chainId: i32
+  ) {}
+}
+
+@json
+export class GetPrice extends GetPriceBase {
+  public readonly timestamp: i64
+
+  constructor(address: string, chainId: i32, timestamp: i64) {
+    super(address, chainId)
+    this.timestamp = timestamp
+  }
+
+  static fromToken(token: Token, timestamp: Date | null): GetPriceBase {
+    const address = token.address.toString()
+    const chainId = token.chainId
+
+    return timestamp
+      ? new GetPrice(address, chainId, changetype<Date>(timestamp).getTime())
+      : new GetPriceBase(address, chainId)
+  }
+}

package/src/queries/GetRelevantTokens.ts

@@ -0,0 +1,82 @@
+import { ListType } from '../helpers'
+import { Token, TokenAmount, USD } from '../tokens'
+import { Address, BigInt, ChainId } from '../types'
+
+@json
+class TokenQuery {
+  constructor(
+    public address: string,
+    public chainId: i32
+  ) {}
+
+  static fromToken(token: Token): TokenQuery {
+    return new TokenQuery(token.address.toString(), token.chainId)
+  }
+}
+
+@json
+class GetRelevantTokensBase {
+  constructor(
+    public readonly owner: string,
+    public readonly chainIds: ChainId[],
+    public readonly usdMinAmount: string,
+    public readonly tokens: TokenQuery[],
+    public readonly tokenFilter: ListType
+  ) {}
+}
+
+@json
+export class GetRelevantTokens extends GetRelevantTokensBase {
+  public readonly timestamp: i64
+
+  constructor(
+    owner: string,
+    chainIds: ChainId[],
+    usdMinAmount: string,
+    tokens: TokenQuery[],
+    tokenFilter: ListType,
+    timestamp: i64
+  ) {
+    super(owner, chainIds, usdMinAmount, tokens, tokenFilter)
+    this.timestamp = timestamp
+  }
+
+  static init(
+    owner: Address,
+    chainIds: ChainId[],
+    usdMinAmount: USD,
+    tokens: Token[],
+    tokenFilter: ListType,
+    timestamp: Date | null = null
+  ): GetRelevantTokensBase {
+    const ownerStr = owner.toString()
+    const usdMinAmountStr = usdMinAmount.toString()
+    const tokensQueries = tokens.map<TokenQuery>((token) => TokenQuery.fromToken(token))
+
+    return timestamp
+      ? new GetRelevantTokens(
+          ownerStr,
+          chainIds,
+          usdMinAmountStr,
+          tokensQueries,
+          tokenFilter,
+          changetype<Date>(timestamp).getTime()
+        )
+      : new GetRelevantTokensBase(ownerStr, chainIds, usdMinAmountStr, tokensQueries, tokenFilter)
+  }
+}
+
+@json
+export class GetRelevantTokensResponse {
+  constructor(
+    public token: TokenQuery,
+    public amount: string
+  ) {}
+
+  toTokenAmount(): TokenAmount {
+    return TokenAmount.fromBigInt(
+      Token.fromString(this.token.address, this.token.chainId),
+      BigInt.fromString(this.amount)
+    )
+  }
+}

package/src/queries/index.ts

@@ -0,0 +1,3 @@
+export * from './Call'
+export * from './GetPrice'
+export * from './GetRelevantTokens'