viem-erc4626

Viem extensions for ERC-4626 tokenized vaults

Installation

Install viem, viem-erc20, and viem-erc4626 as dependencies:

npm install viem viem-erc20 viem-erc4626

Methods

This package provides ESM-friendly helpers for interacting with ERC-4626 vault contracts using viem.

All the methods are named after the ERC-4626:

allowance

Returns the remaining number of tokens that spender will be allowed to spend on behalf of owner through transferFrom. View docs

allowance(client, { address, owner, spender });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)
• owner: Address — Address that owns the tokens (required)
• spender: Address — Address that is allowed to spend the tokens (required)

Example:

import { allowance } from "viem-erc4626/actions";
const allowanceAmount = await allowance(client, {
  address: "0x12345678912345678912345678912345678912345",
  owner: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
  spender: "0x1234567891234567891234567891234567891234",
});

approve

Sets amount as the allowance of spender over the caller's tokens. View docs

approve(client, { address, spender, amount });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)
• spender: Address — Address to approve for spending tokens (required)
• amount: bigint — Amount of tokens to approve (required)

Example:

import { approve } from "viem-erc4626/actions";
const hash = await approve(client, {
  address: "0x12345678912345678912345678912345678912345",
  spender: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
  amount: BigInt("1000000000000000000"), // 1 token
});

asset

Returns the address of the underlying asset of the vault. View docs

asset(client, { address });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)

Example:

import { asset } from "viem-erc4626/actions";
const assetAddress = await asset(client, {
  address: "0x12345678912345678912345678912345678912345",
});

balanceOf

Returns the amount of tokens owned by account. View docs

balanceOf(client, { address, account });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)
• account: Address — Address to check the balance of (required)

Example:

import { balance } from "viem-erc4626/actions";
const tokenBalance = await balanceOf(client, {
  address: "0x12345678912345678912345678912345678912345",
  account: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

convertToAssets

Returns the amount of assets that would be exchanged by the vault for the amount of shares provided. View docs

convertToAssets(client, { address, shares });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• shares: bigint — Amount of shares to convert (required)

Example:

import { convertToAssets } from "viem-erc4626/actions";
const assetAmount = await convertToAssets(client, {
  address: "0x12345678912345678912345678912345678912345",
  shares: BigInt("1000000000000000000"), // 1 share
});

convertToShares

Returns the amount of shares that would be exchanged by the vault for the amount of assets provided. View docs

convertToShares(client, { address, assets });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• assets: bigint — Amount of assets to convert (required)

Example:

import { convertToShares } from "viem-erc4626/actions";
const shareAmount = await convertToShares(client, {
  address: "0x12345678912345678912345678912345678912345",
  assets: BigInt("1000000000000000000"), // 1 asset
});

decimals

Returns the number of decimals used to get its user representation. View docs

decimals(client, { address });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)

Example:

import { decimals } from "viem-erc4626/actions";
const tokenDecimals = await decimals(client, {
  address: "0x12345678912345678912345678912345678912345",
});

deposit

Mints vault shares to receiver by depositing exactly assets of underlying tokens. View docs

deposit(client, { address, assets, receiver });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• assets: bigint — Amount of assets to deposit (required)
• receiver: Address — Address to receive the vault shares (required)

Example:

import { deposit } from "viem-erc4626/actions";
const hash = await deposit(client, {
  address: "0x12345678912345678912345678912345678912345",
  assets: BigInt("1000000000000000000"), // 1 asset
  receiver: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

maxDeposit

Returns the maximum amount of the underlying asset that can be deposited into the vault for the receiver. View docs

maxDeposit(client, { address, receiver });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• receiver: Address — Address that would receive the vault shares (required)

Example:

import { maxDeposit } from "viem-erc4626/actions";
const maxDepositAmount = await maxDeposit(client, {
  address: "0x12345678912345678912345678912345678912345",
  receiver: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

maxMint

Returns the maximum amount of the vault shares that can be minted for the receiver. View docs

maxMint(client, { address, receiver });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• receiver: Address — Address that would receive the vault shares (required)

Example:

import { maxMint } from "viem-erc4626/actions";
const maxMintAmount = await maxMint(client, {
  address: "0x12345678912345678912345678912345678912345",
  receiver: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

maxRedeem

Returns the maximum amount of vault shares that can be redeemed from the owner balance. View docs

maxRedeem(client, { address, owner });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• owner: Address — Address that owns the vault shares (required)

Example:

import { maxRedeem } from "viem-erc4626/actions";
const maxRedeemAmount = await maxRedeem(client, {
  address: "0x12345678912345678912345678912345678912345",
  owner: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

maxWithdraw

Returns the maximum amount of the underlying asset that can be withdrawn from the owner balance. View docs

maxWithdraw(client, { address, owner });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• owner: Address — Address that owns the vault shares (required)

Example:

import { maxWithdraw } from "viem-erc4626/actions";
const maxWithdrawAmount = await maxWithdraw(client, {
  address: "0x12345678912345678912345678912345678912345",
  owner: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

mint

Mints exactly shares vault shares to receiver by depositing assets of underlying tokens. View docs

mint(client, { address, shares, receiver });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• shares: bigint — Amount of shares to mint (required)
• receiver: Address — Address to receive the vault shares (required)

Example:

import { mint } from "viem-erc4626/actions";
const hash = await mint(client, {
  address: "0x12345678912345678912345678912345678912345",
  shares: BigInt("1000000000000000000"), // 1 share
  receiver: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
});

name

Returns the name of the token. View docs

name(client, { address });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)

Example:

import { name } from "viem-erc4626/actions";
const tokenName = await name(client, {
  address: "0x12345678912345678912345678912345678912345",
});

previewDeposit

Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block. View docs

previewDeposit(client, { address, assets });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• assets: bigint — Amount of assets to preview deposit (required)

Example:

import { previewDeposit } from "viem-erc4626/actions";
const expectedShares = await previewDeposit(client, {
  address: "0x12345678912345678912345678912345678912345",
  assets: BigInt("1000000000000000000"), // 1 asset
});

previewMint

Allows an on-chain or off-chain user to simulate the effects of their mint at the current block. View docs

previewMint(client, { address, shares });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• shares: bigint — Amount of shares to preview mint (required)

Example:

import { previewMint } from "viem-erc4626/actions";
const requiredAssets = await previewMint(client, {
  address: "0x12345678912345678912345678912345678912345",
  shares: BigInt("1000000000000000000"), // 1 share
});

previewRedeem

Allows an on-chain or off-chain user to simulate the effects of their redeem at the current block. View docs

previewRedeem(client, { address, shares });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• shares: bigint — Amount of shares to preview redeem (required)

Example:

import { previewRedeem } from "viem-erc4626/actions";
const expectedAssets = await previewRedeem(client, {
  address: "0x12345678912345678912345678912345678912345",
  shares: BigInt("1000000000000000000"), // 1 share
});

previewWithdraw

Allows an on-chain or off-chain user to simulate the effects of their withdraw at the current block. View docs

previewWithdraw(client, { address, assets });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• assets: bigint — Amount of assets to preview withdraw (required)

Example:

import { previewWithdraw } from "viem-erc4626/actions";
const requiredShares = await previewWithdraw(client, {
  address: "0x12345678912345678912345678912345678912345",
  assets: BigInt("1000000000000000000"), // 1 asset
});

redeem

Burns exactly shares from owner and sends assets of underlying tokens to receiver. View docs

redeem(client, { address, shares, receiver, owner });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• shares: bigint — Amount of shares to redeem (required)
• receiver: Address — Address to receive the underlying assets (required)
• owner: Address — Address that owns the vault shares (required)

Example:

import { redeem } from "viem-erc4626/actions";
const hash = await redeem(client, {
  address: "0x12345678912345678912345678912345678912345",
  shares: BigInt("1000000000000000000"), // 1 share
  receiver: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
  owner: "0x1234567891234567891234567891234567891234",
});

symbol

Returns the symbol of the token, usually a shorter version of the name. View docs

symbol(client, { address });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)

Example:

import { symbol } from "viem-erc4626/actions";
const tokenSymbol = await symbol(client, {
  address: "0x12345678912345678912345678912345678912345",
});

totalAssets

Returns the total amount of the underlying asset that is managed by the vault. View docs

totalAssets(client, { address });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)

Example:

import { totalAssets } from "viem-erc4626/actions";
const totalAssetAmount = await totalAssets(client, {
  address: "0x12345678912345678912345678912345678912345",
});

totalSupply

Returns the amount of tokens in existence. View docs

totalSupply(client, { address });

• client: Client — from viem — (required)
• address: Address — ERC-20 token contract address (required)

Example:

import { totalSupply } from "viem-erc4626/actions";
const tokenTotalSupply = await totalSupply(client, {
  address: "0x12345678912345678912345678912345678912345",
});

withdraw

Burns shares from owner and sends exactly assets of underlying tokens to receiver. View docs

withdraw(client, { address, assets, receiver, owner });

• client: Client — from viem — (required)
• address: Address — ERC-4626 vault contract address (required)
• assets: bigint — Amount of assets to withdraw (required)
• receiver: Address — Address to receive the underlying assets (required)
• owner: Address — Address that owns the vault shares (required)

Example:

import { withdraw } from "viem-erc4626/actions";
const hash = await withdraw(client, {
  address: "0x12345678912345678912345678912345678912345",
  assets: BigInt("1000000000000000000"), // 1 asset
  receiver: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
  owner: "0x1234567891234567891234567891234567891234",
});