Getting Started

Overview

reverse-mirage is a set of TypeScript utilities that provide low-level building blocks for Ethereum app development. reverse-mirage is focued on developer experience, stability, bundle size, and performance:

• Developer experience Automatic type safety and inference, comprehensive documentation, expressive types.
• Stability Test suite runs against local Ethereum networks, near complete test coverage.
• Bundle size Tree-shakable and lightweight.
• Performance Optimized arithmetic functions, decoding, and parsing all taking advantage of modern javascript.

reverse-mirage relies heavily on viem. All users should be familiar with this package before continuing.

Types

Tokens

Tokens represent an asset on Ethereum. Currently reverse-mirage has:

• ERC20: Fungible tokens
• ERC721: Non-fungible tokens
• ERC1155: Semi-fungible tokens
• Native: Native currency i.e. Ether
• WETH: ERC20 wrapped native currency

Convenience

Convenience types help make it easier to use Ethereum in TypeScript. This includes:

• Amount: Token amounts with support for decimals
• Price: Exchange rates between tokens with support for decimals

Utilities

There are many functions for creating certain types.

create.ts

import { mainnet } from 'viem/chains'
import {
  createNativeCurrency,
  createAmountFromString,
  createAmountFromRaw,
  } from 'reverse-mirage'

const eth = createNativeCurrency('Ether', 'ETH', 18, mainnet.id)

createAmountFromString(eth, '15')
createAmountFromRaw(1000000000000000000n)

Convenience Utilities

Convenience types also contain certain arithmetic and decoding functions.

amounts.ts

import { mainnet } from 'viem/chains'
import {
  createNativeCurrency,
  createAmountFromString,
  amountAdd,
  amountMultiply,
  amountEqual,
  amountToNumber,
  } from 'reverse-mirage'

const eth = createNativeCurrency('Ether', 'ETH', 18, mainnet.id)
const amount = createAmountFromString(eth, '15')

const a = amountAdd(amount, amount)
const b = amountMultiply(amount, 2)

console.log(amountEqual(a, b)) // true
console.log(amountToNumber(a)) // 30

Read actions

Read actions are used to read data from Ethereum. There are many functions for each token type.

read.ts

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { publicActionsReverseMirage, amountToNumber } from 'reverse-mirage'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
}).extend(publicActionsReverseMirage)

// read token metadata
const usdc = await publicClient.getERC20({
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // usdc
  id: mainnet.id,
})

// read a balance
const vitalikBalance = await publicClient.getERC20Balance({
  erc20: usdc,
  address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // vitalik
})

Write actions

Write actions are used to prepare a transaction for Ethereum. Each token type has its own set of write actions.

read.ts

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
import { publicActionsReverseMirage, amountToNumber } from 'reverse-mirage'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
}).extend(publicActionsReverseMirage)

const usdc = await publicClient.getERC20({
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // usdc
  id: mainnet.id
})

// send usdc
const { request } = await publicClient.simulateERC20Transfer({
  args: { 
    amount: createAmountFromString(usdc, '5'),
    to: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // vitalik
  },
})

Extras

Chains

Known tokens are also exported for popular chains.

chains.ts

import { celoTokens } from 'reverse-mirage'

console.log(celoTokens.native.decimals) // 18
console.log(celoTokens.weth.address) // 0x471E...a438

native and weth are exported for:

• mainnet
• goerli
• sepolia
• celo
• celoAlfajores
• optimism
• optimismGoerli
• base
• baseGoerli
• arbitrum
• arbitrumGoerli

ABIs

erc20, erc721, erc1155, and weth all have a corresponding exported Abi.