Skip to content

ERC-20 token operations: look up a token’s name, symbol, and decimals, resolve its logo, and read an account’s wallet balance.

Reach it as sdk.tokens on an AnvilSDK instance, which creates the module for you.

Methods

getAccountBalance()

getAccountBalance(params): Promise<bigint>;

Returns an account’s wallet balance of one token, in that token’s smallest units.

This is the wallet balance only. Collateral already deposited into the vault is not counted — see VaultModule.getCollateralBalance for that side.

Parameters

ParameterTypeDescription
paramsGetAccountTokenBalanceParamsThe token, and the account whose balance to read.
params.accountAddress?`0x${string}`Wallet to read. Defaults to the configured signer’s address.
params.tokenAddress`0x${string}`ERC-20 whose wallet balance (balanceOf) to read. This is wallet holdings, not vault collateral; for the latter use VaultModule.getCollateralBalance.

Returns

Promise<bigint>

The balance in the token’s smallest units.


getMetadata()

getMetadata(params): Promise<TokenMetadata | undefined>;

Returns the presentation metadata (currently the logo URL) for a token.

The profile’s token aliases are applied automatically, which is what lets a testnet token resolve to its mainnet counterpart’s logo. Passing tokenAliases explicitly overrides the profile’s map.

Parameters

ParameterTypeDescription
paramsGetTokenMetadataParamsThe token to look up, and optional alias overrides.
params.address`0x${string}`Token address to resolve a logo for. An address listed in tokenAliases is mapped to its mainnet counterpart before lookup.
params.tokenAliases?Readonly<Record<`0x${string}`, `0x${string}`>>Map from this environment’s token addresses to their mainnet counterparts. sdk.tokens.getMetadata uses the profile’s tokenAliases when you omit it; pass one to override that map.

Returns

Promise<TokenMetadata | undefined>

The metadata, or undefined when no logo resolves.


getToken()

getToken(params): Promise<Token | undefined>;

Returns the Token at an address: name, symbol, and decimals read from the ERC-20 contract, with logo metadata attached when Anvil’s token logo set has one.

Each call reads the token contract and metadata source. A contract that answers symbol() with an empty string yields undefined rather than throwing.

It is not a general “is this an ERC-20?” probe: an address with no ERC-20 interface at all — an EOA, or an unrelated contract — makes the underlying reads revert, and this throws. Catch if you are checking an address the user supplied.

Parameters

ParameterTypeDescription
paramsGetTokenParamsThe token address to look up.
params.address`0x${string}`ERC-20 contract address. Resolved by reading name/symbol/decimals from the token contract itself (any ERC-20, not only Anvil-registered ones).

Returns

Promise<Token | undefined>

The token, or undefined if the contract reports an empty symbol.

Throws

InvalidArgumentError If params.address is missing. Thrown before any read.


validateApprove()

validateApprove(params): Promise<ValidationIssue[]>;

Validates the parameters of an ERC-20 approve call: address format, and an amount of zero or more. Zero is valid — it is how an approval is revoked.

Unlike the other validate* methods this one has no matching build*Workflow call. Workflows add an ERC-20 approve step on their own when one is needed (the deposit workflow does, when the vault’s approval is short); this method lets you check an approval’s inputs on their own.

Parameters

ParameterTypeDescription
paramsPartial<ERC20ApproveParams>The partial approve parameters to check.
params.amount?bigintAllowance to set, in the token’s smallest unit. This replaces the current allowance rather than adding to it; some tokens (e.g. USDT) reject non-zero to non-zero changes — see buildERC20RevokeTransaction.
params.erc20Address?AddressThe ERC-20 token contract whose approve is being called.
params.from?AddressIf not provided, this will be populated by the configured signer.
params.spender?AddressThe address being granted the allowance. For protocol flows this is the CollateralVault (sdk.getContractAddress(AnvilContract.CollateralVault)), which pulls tokens on deposit.

Returns

Promise<ValidationIssue[]>

The issues found. An empty array means every rule ran and passed; a rule whose required field is missing reports FieldRequired instead of being skipped. An infrastructure failure rejects rather than returning a partial list.