Skill: Writing a Function

A Mimic function is an AssemblyScript module compiled to WebAssembly. It runs inside a sandboxed environment on every trigger execution, receives typed inputs from the manifest, queries on-chain and off-chain data, and emits intents — declarations of what you want to happen on-chain.

---

Project anatomy

my-function/
├── manifest.yaml          # Inputs, ABIs, and metadata
├── src/
│   ├── function.ts        # Your function logic (entry point)
│   └── types/             # Auto-generated by `mimic codegen`
│       ├── index.ts       # Typed inputs
│       └── ERC20.ts       # Generated ABI wrapper (one per ABI)
└── build/
    ├── function.wasm      # Compiled output
    └── manifest.json      # Validated manifest

---

Manifest

The manifest describes your function's metadata, inputs, and contract ABIs. The CLI uses it to validate, generate types, compile, and deploy.

version: 1.0.0
name: My Automation Function
description: Swaps USDC to ETH when balance exceeds a threshold.
inputs:
  - chainId: uint32
  - account: address
  - tokenIn: address
  - tokenOut: address
  - threshold: uint256
  - slippage: uint32
abis:
  - ERC20: "./abis/ERC20.json"

Inputs can optionally include a description:

inputs:
  - amount:
      type: uint256
      description: Amount to transfer in wei
  - recipient:
      type: address
      description: Target account address

• inputs and abis are merged into maps during validation — duplicate keys are rejected.

• ABI paths are resolved relative to the directory of your manifest.yaml.

---

Function structure

Every function must export a main function. The inputs type is auto-generated from your manifest.

import { environment, Ethereum, log, TokenAmount, TransferBuilder } from '@mimicprotocol/lib-ts'
import { Inputs } from './types'

export { Inputs }

export default function main(inputs: Inputs): void {
  // 1. Read inputs
  const account = inputs.account
  const threshold = inputs.threshold

  // 2. Query on-chain or off-chain data
  const balanceResult = environment.relevantTokensQuery(account, [inputs.chainId])
  if (balanceResult.isError) {
    log.error('Failed to query balances: {}', [balanceResult.error])
    return
  }

  // 3. Apply logic and emit intents
  const balances = balanceResult.unwrap()
  // ... build and send an intent
}

---

Library reference (@mimicprotocol/lib-ts)

Primitives

import { Address, BigInt, Bytes } from '@mimicprotocol/lib-ts'

// Address
const addr    = Address.fromString('0x...')
const zero    = Address.zero()

// BigInt — used for all token amounts and large numbers
const amount  = BigInt.fromString('1000000000000000000') // 1 ETH in wei
const doubled = amount.times(BigInt.fromI32(2))
const power   = BigInt.fromI32(10).pow(18)

// Bytes — arbitrary byte data
const data    = Bytes.fromHexString('0x095ea7b3...')
const empty   = Bytes.empty()
const utf8    = Bytes.fromUTF8('hello')

---

Tokens and amounts

Built-in chain namespaces export known tokens and the chain's CHAIN_ID:

import { Ethereum, Base, Arbitrum, Optimism, Gnosis, Polygon, ERC20Token, TokenAmount, USD } from '@mimicprotocol/lib-ts'

// Pre-defined tokens
const usdc = Ethereum.USDC
const eth  = Ethereum.ETH
const wbtc = Ethereum.WBTC

// Custom ERC20 token (address, chainId, decimals, symbol)
const myToken = ERC20Token.fromString('0x...', Ethereum.CHAIN_ID, 18, 'MYT')

// TokenAmount — wraps a token and an amount
const amount   = TokenAmount.fromStringDecimal(usdc, '1000.50')   // 1000.5 USDC
const native   = TokenAmount.fromI32(eth, 5)                       // 5 ETH
const raw      = TokenAmount.fromBigInt(usdc, BigInt.fromString('1000000')) // 1 USDC (6 decimals)

// Price conversions
const usdValue = amount.toUsd().unwrap()                           // USD
const inWbtc   = amount.toTokenAmount(Ethereum.WBTC).unwrap()     // TokenAmount

// USD
const usd      = USD.fromStringDecimal('1000')
const inUsdc   = usd.toTokenAmount(Ethereum.USDC).unwrap()

---

Result type

All queries (except getContext) return Result<V, string>. Always handle errors.

import { Result } from '@mimicprotocol/lib-ts'

const result = environment.tokenPriceQuery(Ethereum.USDC)

// Check state
result.isOk    // true on success
result.isError // true on failure

// Unwrap
result.unwrap()              // throws if error
result.unwrapOr(USD.zero())  // fallback value
result.unwrapOrElse(() => {  // fallback function
  log.warning('Price unavailable, using zero')
  return USD.zero()
})

// Access error message
if (result.isError) log.error('Error: {}', [result.error])

---

Environment queries

Token price

import { environment, Ethereum } from '@mimicprotocol/lib-ts'

// Current USD price (median across sources)
const price = environment.tokenPriceQuery(Ethereum.USDC).unwrap()

// Historical price
const historical = environment.tokenPriceQuery(Ethereum.USDC, new Date(1640995200000)).unwrap()

// Raw samples from all sources (useful for custom aggregation)
const raw = environment.rawTokenPriceQuery(Ethereum.USDC).unwrap()

Relevant token balances

Returns all token balances for an address, with optional chain, allow/deny list, and USD minimum filters.

import { environment, Address, ChainId, ListType, USD } from '@mimicprotocol/lib-ts'

// All tokens on Ethereum and Polygon worth at least $100, excluding USDT
const tokens = environment.relevantTokensQuery(
  userAddress,
  [ChainId.ETHEREUM, ChainId.POLYGON],
  USD.fromStringDecimal('100'),
  [Ethereum.USDT],
  ListType.DenyList
).unwrap()  // TokenAmount[]

EVM contract read (raw)

Use generated ABI wrappers (see below) instead of raw calls where possible.

const response = environment.evmCallQuery(
  Address.fromString('0xcontract'),
  ChainId.ETHEREUM,
  '0x70a08231' + encodedArgs,  // selector + ABI-encoded params
  null                          // optional timestamp
).unwrap()  // raw hex string

Native token balance

const balance = environment.getNativeTokenBalance(ChainId.ETHEREUM, userAddress).unwrap() // BigInt in wei

Account code

const code = environment.getCode(ChainId.ETHEREUM, contractAddress).unwrap() // Bytes

Subgraph query

const result = environment.subgraphQuery(
  ChainId.ETHEREUM,
  'QmSubgraphId',
  '{ tokens(first: 5) { id symbol } }',
  null  // optional timestamp
).unwrap()  // SubgraphQueryResult

Execution context

getContext() does not return a Result — it cannot fail.

import { environment, ChainId } from '@mimicprotocol/lib-ts'

const ctx = environment.getContext()

ctx.user               // Address — the user this trigger belongs to
ctx.timestamp          // u64 — current execution timestamp in milliseconds
ctx.consensusThreshold // u8 — minimum number of agreeing relayers required
ctx.triggerSig         // string — unique signature of the trigger
ctx.settlers           // Settler[] — available settler contracts

// Get the settler address for a specific chain
const settler = ctx.findSettler(ChainId.ETHEREUM)

// Access trigger payload data
const payload = ctx.triggerPayload
if (payload.type == TriggerType.CRON) {
  const scheduleTimestamp = payload.getCronData()  // BigInt
}
if (payload.type == TriggerType.EVENT) {
  const eventData = payload.getEventData()
  // eventData.chainId, eventData.contract, eventData.topics, eventData.eventData
}

---

Generated ABI wrappers

After running mimic codegen, each ABI declared in the manifest produces a typed wrapper in src/types/<ContractName>.ts.

Read methods call the contract and return Result<T, string>:

import { ChainId } from '@mimicprotocol/lib-ts'
import { ERC20 } from './types/ERC20'

const token = new ERC20(tokenAddress, ChainId.ETHEREUM)

const balanceResult = token.balanceOf(userAddress)  // Result<BigInt, string>
if (balanceResult.isError) return
const balance = balanceResult.unwrap()

// Optional: query at a specific timestamp
const historicalToken = new ERC20(tokenAddress, ChainId.ETHEREUM, new Date(1640995200000))

Write methods return an EvmCallBuilder — they do not call the environment directly:

const approveBuilder = token.approve(spenderAddress, amount)  // EvmCallBuilder
// chain more calls or call .addMaxFee(...).build().send()

Type mapping summary

Solidity	AssemblyScript
address	Address
bool	bool
string	string
bytes / bytesN	Bytes
uint8–uint16, int8–int16	u8/u16/i8/i16
uint32–uint64, int32–int64	u32/u64/i32/i64
uint256, int256 (N ≥ 24)	BigInt
T[]	T[]
tuple / struct	generated class

---

Intent builders

Intents are declarations of what you want to happen. The protocol finds the best way to fulfill them.

Transfer — move tokens between addresses

import { Address, ChainId, Ethereum, TokenAmount, TransferBuilder } from '@mimicprotocol/lib-ts'

const fee = TokenAmount.fromStringDecimal(Ethereum.USDC, '1')

TransferBuilder.forChain(ChainId.ETHEREUM)
  .addTransferFromStringDecimal(Ethereum.USDC, '500', recipientAddress)
  .addTransferFromStringDecimal(Ethereum.WBTC, '0.01', recipientAddress)
  .addMaxFee(fee)
  .build()
  .send()

Shorthand for a single-token transfer:

import { Transfer } from '@mimicprotocol/lib-ts'

Transfer.create(Ethereum.USDC, amount, recipient, maxFeeAmount).send()

All input amounts (token, fee) must be on the same chain as the builder.

Swap — exchange tokens

import { ChainId, Ethereum, SwapBuilder, TokenAmount } from '@mimicprotocol/lib-ts'

const fee = TokenAmount.fromStringDecimal(Ethereum.USDC, '1')

// Same-chain swap
SwapBuilder.forChain(ChainId.ETHEREUM)
  .addTokenInFromStringDecimal(Ethereum.USDC, '1000')
  .addTokenOutFromStringDecimal(Ethereum.USDT, '990', recipientAddress)  // min amount out
  .addMaxFee(fee)
  .build()
  .send()

// Cross-chain swap
SwapBuilder.forChains(ChainId.ETHEREUM, ChainId.ARBITRUM)
  .addTokenInFromStringDecimal(Ethereum.USDC, '1000')
  .addTokenOutFromStringDecimal(Arbitrum.USDC, '990', recipientAddress)
  .addMaxFee(fee)
  .build()
  .send()

The tokenOut amount is a minimum — relayers may deliver more.

Shorthand for a simple single-chain swap (recipient defaults to ctx.user):

import { Swap } from '@mimicprotocol/lib-ts'

Swap.create(ChainId.ETHEREUM, Ethereum.USDC, amountIn, Ethereum.ETH, minAmountOut).send()

EVM Call — execute contract functions

import { Address, ChainId, Ethereum, EvmCallBuilder, TokenAmount } from '@mimicprotocol/lib-ts'
import { MyContract } from './types/MyContract'

const contract = new MyContract(contractAddress, ChainId.ETHEREUM)
const fee = TokenAmount.fromStringDecimal(Ethereum.USDC, '1')

// Using generated wrapper (preferred)
contract.myFunction(arg1, arg2)       // returns EvmCallBuilder
  .addMaxFee(fee)
  .build()
  .send()

// Multiple calls in one intent
EvmCallBuilder.forChain(ChainId.ETHEREUM)
  .addCall(contractAddress, encodedData1)
  .addCall(contractAddress, encodedData2)
  .addMaxFee(fee)
  .build()
  .send()

Common builder options

All intent builders support these optional methods before .build():

Method	Purpose
.addSettler(address)	Override the settler contract (defaults to context settler)
.addUser(address)	Override the user (defaults to ctx.user)
.addDeadline(timestamp)	Override the deadline (defaults to 5 minutes from now)
.addNonce(string)	Override the nonce (defaults to auto-generated)
.addEvent(topic, data)	Attach an on-chain event to the intent
.addEvents(events[])	Attach multiple events

---

Persistent storage

Use the storage namespace to read and write arbitrary bytes to the user's on-chain storage via the Mimic Helper contract. Useful for maintaining state between executions.

import { environment, Ethereum, TokenAmount } from '@mimicprotocol/lib-ts'
import { storage } from '@mimicprotocol/lib-ts/storage'
import { Bytes, ChainId } from '@mimicprotocol/lib-ts'

const userAddress = environment.getContext().user
const fee = TokenAmount.fromStringDecimal(Ethereum.USDC, '0.5')

// Write — emits an EvmCall intent that stores the data on-chain
storage.createSetDataCall(
  userAddress,
  fee,
  'last-execution',                    // storage key
  Bytes.fromUTF8('2024-01-01'),        // value (arbitrary bytes)
  ChainId.OPTIMISM                     // chain (defaults to Optimism)
).send()

// Read — synchronous on-chain call, returns Result<Bytes, string>
const dataResult = storage.getData(userAddress, 'last-execution', ChainId.OPTIMISM)
if (dataResult.isOk) {
  const value = dataResult.unwrap().toString()
}

---

Logging

import { log } from '@mimicprotocol/lib-ts'

log.debug('Processing account {}', [account.toHexString()])
log.info('Balance: {} USDC', [balance.toString()])
log.warning('Slippage is high: {}%', [slippage.toString()])
log.error('Token price query failed: {}', [result.error])

// CRITICAL terminates execution immediately
log.critical('Unexpected state, aborting')

Use {} as a placeholder; arguments are injected in order. Levels: DEBUG < INFO < WARNING < ERROR < CRITICAL.

---

EVM utilities

import { evm, EvmEncodeParam, EvmDecodeParam, Address, BigInt } from '@mimicprotocol/lib-ts'

// ABI-encode parameters
const encoded = evm.encode([
  EvmEncodeParam.fromValue('address', Address.zero()),
  EvmEncodeParam.fromValue('uint256', BigInt.fromI32(100)),
])

// ABI-decode a response
const decoded = evm.decode(new EvmDecodeParam('uint256', responseHex))

// Keccak-256 hash
const hash = evm.keccak('some data')

---

Putting it together — annotated example

import {
  Address, ChainId, Ethereum, environment, log,
  SwapBuilder, TokenAmount, USD,
} from '@mimicprotocol/lib-ts'
import { Inputs } from './types'
import { ERC20 } from './types/ERC20'

export { Inputs }

export default function main(inputs: Inputs): void {
  const ctx     = environment.getContext()
  const account = ctx.user
  const token   = new ERC20(inputs.tokenIn, ChainId.ETHEREUM)

  // Read on-chain balance
  const balResult = token.balanceOf(account)
  if (balResult.isError) {
    log.error('balanceOf failed: {}', [balResult.error])
    return
  }
  const balance = balResult.unwrap()

  // Check threshold
  const threshold = inputs.threshold
  if (balance.lt(threshold)) {
    log.info('Balance {} below threshold {}, skipping', [balance.toString(), threshold.toString()])
    return
  }

  // Swap to ETH
  const fee = TokenAmount.fromStringDecimal(Ethereum.USDC, '1')
  const minOut = TokenAmount.fromBigInt(Ethereum.ETH, balance)
    .toTokenAmount(Ethereum.ETH).unwrap()

  SwapBuilder.forChain(ChainId.ETHEREUM)
    .addTokenInFromStringDecimal(Ethereum.USDC, balance.toString())
    .addTokenOutFromTokenAmount(minOut, account)
    .addMaxFee(fee)
    .build()
    .send()

  log.info('Swap intent emitted', [])
}