@mimicprotocol/lib-ts 0.0.1-rc.9

package/README.md

@@ -0,0 +1,90 @@
+<h1 align="center">
+  <a href="https://mimic.fi"><img src="https://www.mimic.fi/logo.png" alt="Mimic Protocol" width="200"></a> 
+</h1>
+
+<h4 align="center">Blockchain automation protocol</h4>
+
+<p align="center">
+  <a href="https://github.com/mimic-protocol/tooling/actions/workflows/ci.yml">
+    <img src="https://github.com/mimic-protocol/tooling/actions/workflows/ci.yml/badge.svg" alt="Build">
+  </a>
+  <a href="https://discord.mimic.fi">
+    <img alt="Discord" src="https://img.shields.io/discord/989984112397922325">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#content">Content</a> •
+  <a href="#setup">Setup</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#security">Security</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+## Content 
+
+This package provides a lightweight standard library for writing Mimic Protocol tasks in AssemblyScript. It includes:
+
+- Typed primitives to interact with oracles and contracts
+- Safe and minimal bindings for blockchain-specific operations
+- Utility helpers for developing deterministic, deployable task logic
+
+## Setup
+
+To set up this project you'll need [git](https://git-scm.com) and [yarn](https://classic.yarnpkg.com) installed. 
+
+Install the library from the root of the monorepo:
+
+```bash
+# Clone this repository
+$ git clone https://github.com/mimic-protocol/tooling
+
+# Go into the repository
+$ cd tooling
+
+# Install dependencies
+$ yarn
+```
+
+## Usage
+
+Here’s an example of how to use the library in a Mimic task:
+
+```ts
+import { environment, Token } from '@mimicprotocol/lib-ts'
+
+const USDC = Token.fromString('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', 1)
+
+environment.getPrice(USDC, new Date(1744818017000))
+```
+
+For full task development guide and examples please visit [docs.mimic.fi](https://docs.mimic.fi/)
+
+## Security
+
+To read more about our auditing and related security processes please refer to the [security section](https://docs.mimic.fi/miscellaneous/security) of our docs site.
+
+However, if you found any potential issue in any of our smart contracts or in any piece of code you consider critical
+for the safety of the protocol, please contact us through <a href="mailto:security@mimic.fi">security@mimic.fi</a>.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0.  
+See the [LICENSE](../../LICENSE) file for details.
+
+### Third-Party Code
+
+This project includes code from [The Graph Tooling](https://github.com/graphprotocol/graph-tooling), licensed under the MIT License.  
+See the [LICENSE-MIT](https://github.com/graphprotocol/graph-tooling/blob/27659e56adfa3ef395ceaf39053dc4a31e6d86b7/LICENSE-MIT) file for details.
+Their original license and attribution are preserved.
+
+
+---
+
+> Website [mimic.fi](https://mimic.fi) &nbsp;&middot;&nbsp;
+> Docs [docs.mimic.fi](https://docs.mimic.fi) &nbsp;&middot;&nbsp;
+> GitHub [@mimic-fi](https://github.com/mimic-fi) &nbsp;&middot;&nbsp;
+> Twitter [@mimicfi](https://twitter.com/mimicfi) &nbsp;&middot;&nbsp;
+> Discord [mimic](https://discord.mimic.fi)

package/index.ts

@@ -0,0 +1,7 @@
+export * from './src/chains'
+export * from './src/environment'
+export * from './src/evm'
+export * from './src/helpers'
+export * from './src/intents'
+export * from './src/tokens'
+export * from './src/types'

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mimicprotocol/lib-ts",
+  "version": "0.0.1-rc.9",
+  "license": "GPL-3.0",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "build": "asc index.ts -b build/lib.wasm --disableWarning 235 --noEmit --transform json-as/transform",
+    "test": "asp",
+    "lint": "eslint . --ignore-pattern 'src/environment.ts' --ignore-pattern 'src/evm.ts'"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "asconfig.json"
+  ],
+  "devDependencies": {
+    "@as-pect/cli": "8.1.0",
+    "assemblyscript": "0.27.36"
+  },
+  "dependencies": {
+    "eslint-config-mimic": "^0.0.3",
+    "json-as": "1.0.7",
+    "visitor-as": "0.11.4"
+  }
+}

package/src/chains/Ethereum.ts

@@ -0,0 +1,12 @@
+import { Token } from '../tokens'
+import { ChainId } from '../types'
+
+export namespace Ethereum {
+  export const CHAIN_ID = ChainId.ETHEREUM
+  export const ETH = Token.native(CHAIN_ID)
+  export const USDC = Token.fromString('0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', CHAIN_ID, 6, 'USDC')
+  export const USDT = Token.fromString('0xdac17f958d2ee523a2206206994597c13d831ec7', CHAIN_ID, 6, 'USDT')
+  export const DAI = Token.fromString('0x6b175474e89094c44da98b954eedeac495271d0f', CHAIN_ID, 18, 'DAI')
+  export const WBTC = Token.fromString('0x2260fac5e5542a773aa44fbcfedf7c193bc2c599', CHAIN_ID, 8, 'WBTC')
+  export const WETH = Token.fromString('0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', CHAIN_ID, 18, 'WETH')
+}

package/src/chains/Optimism.ts

@@ -0,0 +1,12 @@
+import { Token } from '../tokens'
+import { ChainId } from '../types'
+
+export namespace Optimism {
+  export const CHAIN_ID = ChainId.OPTIMISM
+  export const ETH = Token.native(CHAIN_ID)
+  export const USDC = Token.fromString('0x0b2c639c533813f4aa9d7837caf62653d097ff85', CHAIN_ID, 6, 'USDC')
+  export const USDT = Token.fromString('0x94b008aa00579c1307b0ef2c499ad98a8ce58e58', CHAIN_ID, 6, 'USDT')
+  export const DAI = Token.fromString('0xda10009cbd5d07dd0cecc66161fc93d7c9000da1', CHAIN_ID, 18, 'DAI')
+  export const WBTC = Token.fromString('0x68f180fcce6836688e9084f035309e29bf0a2095', CHAIN_ID, 8, 'WBTC')
+  export const WETH = Token.fromString('0x4200000000000000000000000000000000000006', CHAIN_ID, 18, 'WETH')
+}

package/src/chains/Polygon.ts

@@ -0,0 +1,12 @@
+import { Token } from '../tokens'
+import { ChainId } from '../types'
+
+export namespace Polygon {
+  export const CHAIN_ID = ChainId.POLYGON
+  export const POL = Token.native(CHAIN_ID)
+  export const USDC = Token.fromString('0x3c499c542cef5e3811e1192ce70d8cc03d5c3359', CHAIN_ID, 6, 'USDC')
+  export const USDT = Token.fromString('0xc2132d05d31c914a87c6611c10748aeb04b58e8f', CHAIN_ID, 6, 'USDT')
+  export const DAI = Token.fromString('0x8f3cf7ad23cd3cadbd9735aff958023239c6a063', CHAIN_ID, 18, 'DAI')
+  export const WBTC = Token.fromString('0x1bfd67037b42cf73acf2047067bd4f2c47d9bfd6', CHAIN_ID, 8, 'WBTC')
+  export const WETH = Token.fromString('0x7ceb23fd6bc0add59e62ac25578270cff1b9f619', CHAIN_ID, 18, 'WETH')
+}

package/src/chains/index.ts

@@ -0,0 +1,3 @@
+export * from './Ethereum'
+export * from './Optimism'
+export * from './Polygon'

package/src/context/Context.ts

@@ -0,0 +1,29 @@
+import { Address } from '../types'
+
+@json
+export class SerializableContext {
+  constructor(
+    public readonly timestamp: u64,
+    public user: string,
+    public settler: string,
+    public configId: string
+  ) {}
+}
+
+export class Context {
+  constructor(
+    public readonly timestamp: u64,
+    public user: Address,
+    public settler: Address,
+    public configId: string
+  ) {}
+
+  static fromSerializable(serializable: SerializableContext): Context {
+    return new Context(
+      serializable.timestamp,
+      Address.fromString(serializable.user),
+      Address.fromString(serializable.settler),
+      serializable.configId
+    )
+  }
+}

package/src/context/index.ts

@@ -0,0 +1 @@
+export * from './Context'

package/src/environment.ts

@@ -0,0 +1,126 @@
+import { join, ListType, serialize, serializeArray } from './helpers'
+import { Token, TokenAmount, USD } from './tokens'
+import { Address, BigInt, ChainId } from './types'
+import { Swap, Transfer, Call } from './intents'
+import { Call as CallQuery } from './queries'
+import { JSON } from 'json-as/assembly'
+import { Context, SerializableContext } from './context'
+
+export namespace environment {
+  @external('environment', '_call')
+  declare function _call(params: string): void
+
+  @external('environment', '_swap')
+  declare function _swap(params: string): void
+
+  @external('environment', '_transfer')
+  declare function _transfer(params: string): void
+
+  @external('environment', '_getPrice')
+  declare function _getPrice(params: string): string
+
+  @external('environment', '_getRelevantTokens')
+  declare function _getRelevantTokens(params: string): string
+
+  @external('environment', '_contractCall')
+  declare function _contractCall(params: string): string
+
+  @external('environment', '_getContext')
+  declare function _getContext(): string
+
+  /**
+   * Generates a Call intent containing contract calls on the blockchain.
+   * @param call - The Call intent to generate
+   */
+  export function call(call: Call): void {
+    _call(JSON.stringify(call))
+  }
+
+  /**
+   * Generates a Swap intent for token exchange operations.
+   * @param swap - The Swap intent to generate
+   */
+  export function swap(swap: Swap): void {
+    _swap(JSON.stringify(swap))
+  }
+
+  /**
+   * Generates a Transfer intent for sending tokens to recipients.
+   * @param transfer - The Transfer intent to generate
+   */
+  export function transfer(transfer: Transfer): void {
+    _transfer(JSON.stringify(transfer))
+  }
+
+  /**
+   * Tells the price of a token in USD at a specific timestamp.
+   * @param token - The token to get the price of
+   * @param timestamp - The timestamp for price lookup (optional, defaults to current time)
+   * @returns The token price in USD
+   */
+  export function getPrice(token: Token, timestamp: Date | null = null): USD {
+    const price = _getPrice(join([serialize(token.address), serialize(token.chainId), serialize(timestamp ? timestamp.getTime().toString() : '')]))
+    return USD.fromBigInt(BigInt.fromString(price))
+  }
+
+  /**
+   * Tells the balances of an address for the specified tokens and chains.
+   * @param address - The address to query balances for
+   * @param chainIds - Array of chain ids to search
+   * @param usdMinAmount - Minimum USD value threshold for tokens (optional, defaults to zero)
+   * @param tokensList - List of tokens to include/exclude (optional, defaults to empty array)
+   * @param listType - Whether to include (AllowList) or exclude (DenyList) the tokens in `tokensList` (optional, defaults to DenyList)
+   * @returns Array of TokenAmount objects representing the relevant tokens
+   */
+  export function getRelevantTokens(
+    address: Address,
+    chainIds: ChainId[],
+    usdMinAmount: USD = USD.zero(),
+    tokensList: Token[] = [],
+    listType: ListType = ListType.DenyList
+  ): TokenAmount[] {
+    const response = _getRelevantTokens(
+      // NOTE: The runner expects an optional timestamp that the user will not be able to input
+      // that's why serialize('') is used
+      // this is a workaround until a decision is made regarding the timestamp
+      join([serialize(address), serializeArray(chainIds), serialize(usdMinAmount.value), serializeArray(tokensList), serialize(listType), serialize('')])
+    )
+    const rows = response.split('\n')
+    const tokenAmounts: TokenAmount[] = []
+
+    for (let i = 0; i < rows.length; i++) {
+      if (rows[i].length === 0) continue
+      tokenAmounts.push(TokenAmount.parse(rows[i]))
+    }
+
+    return tokenAmounts
+  }
+
+  /**
+   * Generates a contract call of a read function on the blockchain and returns the result.
+   * @param to - The contract address to call
+   * @param chainId - The blockchain network identifier
+   * @param timestamp - The timestamp for the call context (optional)
+   * @param data - The encoded function call data
+   * @returns The raw response from the contract call
+   */
+  export function contractCall(
+    to: Address,
+    chainId: ChainId,
+    timestamp: Date | null,
+    data: string
+  ): string {
+    return _contractCall(
+      JSON.stringify(new CallQuery(to, chainId, timestamp, data))
+    )
+  }
+
+  /**
+   * Tells the current execution context containing environment information.
+   * @returns The Context object containing: user, settler, timestamp, and config ID
+   */
+  export function getContext(): Context {
+    const context = JSON.parse<SerializableContext>(_getContext())
+    return Context.fromSerializable(context)
+  }
+}

package/src/evm.ts

@@ -0,0 +1,40 @@
+import { EvmDecodeParam, EvmEncodeParam } from './types'
+import { join, serialize, serializeArray } from './helpers'
+
+export namespace evm {
+  @external('evm', '_encode')
+  declare function _encode(params: string): string
+
+  @external('evm', '_decode')
+  declare function _decode(params: string): string
+
+  @external('evm', '_keccak')
+  declare function _keccak(params: string): string
+  
+  /**
+   * Encodes parameters for EVM smart contract function calls using ABI encoding.
+   * @param callParameters - Array of parameters to encode for the contract call
+   * @returns The ABI-encoded data as a hex string
+   */
+  export function encode(callParameters: EvmEncodeParam[]): string {
+    return _encode(join([serializeArray(callParameters)]))
+  }
+
+  /**
+   * Decodes EVM contract call response data according to specified types.
+   * @param encodedData - The encoded data configuration specifying how to decode the response
+   * @returns The decoded data as a formatted string
+   */
+  export function decode(encodedData: EvmDecodeParam): string {
+    return _decode(serialize(encodedData))
+  }
+
+  /**
+   * Computes the Keccak-256 hash of the input data.
+   * @param data - The input data to hash
+   * @returns The Keccak-256 hash as a hex string
+   */
+  export function keccak(data: string): string {
+    return _keccak(data)
+  }
+}

package/src/helpers/constants.ts

@@ -0,0 +1,9 @@
+export const NULL_ADDRESS = '0x0000000000000000000000000000000000000000'
+export const NATIVE_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
+
+export const STANDARD_DECIMALS: u8 = 18
+
+export enum ListType {
+  AllowList = 0,
+  DenyList = 1,
+}

package/src/helpers/index.ts

@@ -0,0 +1,3 @@
+export * from './constants'
+export * from './serialize'
+export * from './strings'

package/src/helpers/serialize.ts

@@ -0,0 +1,140 @@
+const SEPARATOR = ','
+
+export interface Stringable {
+  toString(): string
+}
+
+export interface Serializable {
+  serialize(): string
+}
+
+export function serialize<T extends Stringable>(elem: T): string {
+  // eslint-disable-next-line
+  // @ts-ignore
+  if (elem instanceof Serializable) return elem.serialize()
+  return elem.toString()
+}
+
+export function serializeArray<T extends Stringable>(array: T[]): string {
+  const serializedElems: (string | null)[] = []
+  for (let i = 0; i < array.length; i++) {
+    serializedElems.push(serialize(array[i]))
+  }
+  return 'Array(' + join(serializedElems) + ')'
+}
+
+export function join(lst: (string | null)[]): string {
+  return lst.join(SEPARATOR)
+}
+
+/**
+ * Parses a CSV string into an array of tokens, handling nested structures,
+ * null values, and stripping one layer of outer parentheses if they wrap the entire string.
+ *
+ * @param csvString - String containing comma-separated values, nested structures (e.g., "(1,2)"), and nulls
+ * @returns Array of strings (trimmed) and nulls, preserving internal nesting
+ * @throws {Error} If parentheses are unbalanced
+ */
+export function parseCSV(csvString: string): (string | null)[] {
+  const tokens: (string | null)[] = []
+  const currentTokenChars: string[] = []
+  const len = csvString.length
+  let depth: i32 = 0
+  let isEmpty = true
+
+  let shouldStripOuter = false
+  if (len > 1 && csvString.charAt(0) == '(' && csvString.charAt(len - 1) == ')') {
+    let balance = 0
+    let firstParenMatchesLast = true
+    for (let k = 0; k < len; k++) {
+      if (csvString.charAt(k) == '(') {
+        balance++
+      } else if (csvString.charAt(k) == ')') {
+        balance--
+      }
+      if (balance == 0 && k < len - 1) {
+        firstParenMatchesLast = false
+        break
+      }
+    }
+    if (firstParenMatchesLast && balance == 0) {
+      shouldStripOuter = true
+    }
+  }
+
+  for (let i = 0; i < len; i++) {
+    const char = csvString.charAt(i)
+    const charCode = char.charCodeAt(0)
+
+    switch (charCode) {
+      case '('.charCodeAt(0):
+        if (shouldStripOuter && i == 0) {
+          depth++
+          break
+        }
+        depth++
+        currentTokenChars.push(char)
+        isEmpty = false
+        break
+
+      case ')'.charCodeAt(0):
+        if (shouldStripOuter && i == len - 1) {
+          depth--
+          break
+        }
+        depth--
+        if (depth < 0) throw new Error(`Unbalanced parentheses at position ${i}`)
+        currentTokenChars.push(char)
+        isEmpty = false
+        break
+
+      case SEPARATOR.charCodeAt(0):
+        const isTopLevelComma = (shouldStripOuter && depth == 1) || (!shouldStripOuter && depth == 0)
+        if (isTopLevelComma) {
+          if (isEmpty) {
+            tokens.push(null)
+          } else {
+            tokens.push(currentTokenChars.join('').trim())
+          }
+          currentTokenChars.length = 0
+          isEmpty = true
+        } else {
+          currentTokenChars.push(char)
+          isEmpty = false
+        }
+        break
+
+      default:
+        currentTokenChars.push(char)
+        isEmpty = false
+        break
+    }
+  }
+
+  if (depth != 0) throw new Error('Unbalanced parentheses at the end of the string')
+
+  if (len > 0) {
+    if (isEmpty) {
+      tokens.push(null)
+    } else {
+      tokens.push(currentTokenChars.join('').trim())
+    }
+  }
+
+  return tokens
+}
+
+/**
+ * Parses a CSV string into an array of strings, throwing an error if any null values are present.
+ *
+ * @param csvString - String containing comma-separated values
+ * @returns Array of strings
+ * @throws {Error} If null values are present
+ */
+
+export function parseCSVNotNullable(csvString: string): string[] {
+  const tokens = parseCSV(csvString)
+  if (tokens.some((token) => token === null)) throw new Error('Null value found in CSV string')
+
+  return changetype<string[]>(tokens)
+}

package/src/helpers/strings.ts

@@ -0,0 +1,103 @@
+export function bytesToString(bytes: Uint8Array): string {
+  return String.UTF8.decodeUnsafe(bytes.dataStart, bytes.length)
+}
+
+export function bytesToHexString(bytes: Uint8Array): string {
+  let hex = '0x'
+  for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, '0')
+  return hex
+}
+
+export function areAllZeros(str: string): boolean {
+  for (let i = 0; i < str.length; i++) if (str.charCodeAt(i) !== 48) return false
+  return true
+}
+
+export function normalizeScientificNotation(input: string): string {
+  let len = input.length
+  if (len === 0) return input
+
+  let i = 0
+  let sign = ''
+  if (input.charAt(0) === '-' || input.charAt(0) === '+') {
+    sign = input.charAt(0)
+    i++
+  }
+
+  let intPart = ''
+  let fracPart = ''
+  let exponentStr = ''
+  let hasDot = false
+  let hasExponent = false
+  let exponentNegative = false
+
+  // Parse integer & fraction parts
+  for (; i < len; i++) {
+    const c = input.charAt(i)
+    if (c === '.') {
+      hasDot = true
+      continue
+    }
+
+    if (c === 'e' || c === 'E') {
+      hasExponent = true
+      i++
+      break
+    }
+
+    if (hasDot) {
+      fracPart += c
+    } else {
+      intPart += c
+    }
+  }
+
+  // Parse exponent if present
+  if (hasExponent) {
+    if (i < len && (input.charAt(i) === '+' || input.charAt(i) === '-')) {
+      exponentNegative = input.charAt(i) === '-'
+      i++
+    }
+
+    for (; i < len; i++) {
+      const char = input.charAt(i)
+      if (char < '0' || char > '9') throw new Error(`Invalid character in exponent part: ${char}`)
+      exponentStr += char
+    }
+  }
+
+  if (exponentStr.length === 0) return input
+
+  const exponent = I32.parseInt(exponentStr)
+  const fullDigits = intPart + fracPart
+  const shift = exponentNegative ? -exponent : exponent
+  const newDecimalPos = intPart.length + shift
+
+  if (newDecimalPos <= 0) {
+    const zeros = '0'.repeat(-newDecimalPos)
+    return sign + '0.' + zeros + fullDigits
+  } else if (newDecimalPos >= fullDigits.length) {
+    const zeros = '0'.repeat(newDecimalPos - fullDigits.length)
+    return sign + fullDigits + zeros
+  } else {
+    return sign + fullDigits.substring(0, newDecimalPos) + '.' + fullDigits.substring(newDecimalPos)
+  }
+}
+
+export function isHex(str: string, strict: boolean = false): boolean {
+  const hasPrefix = str.startsWith('0x')
+
+  if (strict && !hasPrefix) return false
+
+  const value = hasPrefix ? str.slice(2) : str
+
+  for (let i = 0; i < value.length; i++) {
+    const c = value.charCodeAt(i)
+    const isDigit = c >= '0'.charCodeAt(0) && c <= '9'.charCodeAt(0)
+    const isLetter =
+      (c >= 'a'.charCodeAt(0) && c <= 'f'.charCodeAt(0)) || (c >= 'A'.charCodeAt(0) && c <= 'F'.charCodeAt(0))
+    if (!(isDigit || isLetter)) return false
+  }
+
+  return true
+}