One command to start building dApps: npm install -g @web3marketlabs/cli. Install w3m →
Package: @web3marketlabs/sdkAddresses

Addresses

Utilities for managing contract deployment addresses across multiple chains. The address registry pattern maps chain IDs to deployed contract addresses, making it straightforward to work with contracts deployed to multiple networks.

import { getAddress, hasAddress, loadDeployments } from '@web3marketlabs/sdk'

AddressRegistry Type

type AddressRegistry = Record<number, `0x${string}`>

A mapping from numeric chain ID to a 0x-prefixed hex contract address. This is the core type used throughout the address management system.

const myTokenAddresses: AddressRegistry = {
  1: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',       // Ethereum mainnet
  137: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',      // Polygon
  11155111: '0x1234567890abcdef1234567890abcdef12345678',  // Sepolia
}

loadDeployments(deploymentsDir)

Reads all .json deployment files from a directory and builds a map of contract name to AddressRegistry.

function loadDeployments(deploymentsDir: string): Record<string, AddressRegistry>

Parameters

ParameterTypeDescription
deploymentsDir*stringAbsolute or relative path to the directory containing deployment JSON files.
Example: ./deployments

Deployment File Format

Each .json file in the directory represents a single contract. The filename (without .json extension) becomes the contract name. The file contents map chain ID strings to hex addresses:

// deployments/Token.json
{
  "1": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "11155111": "0x1234567890abcdef1234567890abcdef12345678"
}

Returns

A Record<string, AddressRegistry> where each key is a contract name (derived from the filename) and each value is an AddressRegistry.

Example

import { loadDeployments } from '@web3marketlabs/sdk'
 
const contracts = loadDeployments('./deployments')
 
contracts.Token[1]         // '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
contracts.Token[11155111]  // '0x1234...'

Error Handling

loadDeployments throws in the following cases:

ConditionError Message
Directory cannot be readFailed to read deployments directory: {dir}
A JSON file cannot be readFailed to read deployment file: {filePath}
A file contains invalid JSONInvalid JSON in deployment file: {filePath}
A chain ID key is not a valid numberInvalid chain ID "{key}" in deployment file: {filePath}
An address does not start with 0xInvalid address "{address}" for chain {chainId} in {filePath}: must start with 0x

getAddress(registry, chainId)

Get a specific contract address from a registry for a given chain.

function getAddress(registry: AddressRegistry, chainId: number): `0x${string}`

Parameters

ParameterTypeDescription
registry*AddressRegistryThe address registry to look up.
chainId*numberThe numeric chain ID to retrieve the address for.
Example: 1

Returns

The 0x-prefixed contract address for the given chain.

Throws

Throws an Error if no address is registered for the given chain ID:

No address found for chain ID {chainId}. Available chains: {comma-separated list}

Example

import { getAddress, loadDeployments } from '@web3marketlabs/sdk'
 
const contracts = loadDeployments('./deployments')
 
const tokenAddress = getAddress(contracts.Token, 1)
// '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
 
// Throws if chain not found
getAddress(contracts.Token, 42161)
// Error: No address found for chain ID 42161. Available chains: 1, 11155111

hasAddress(registry, chainId)

Check whether an address registry contains an entry for the given chain.

function hasAddress(registry: AddressRegistry, chainId: number): boolean

Parameters

ParameterTypeDescription
registry*AddressRegistryThe address registry to check.
chainId*numberThe numeric chain ID to check for.
Example: 1

Returns

true if the registry has an address for this chain, false otherwise.

Example

import { hasAddress, loadDeployments } from '@web3marketlabs/sdk'
 
const contracts = loadDeployments('./deployments')
 
hasAddress(contracts.Token, 1)      // true
hasAddress(contracts.Token, 42161)  // false
 
// Use with getAddress for safe lookups
if (hasAddress(contracts.Token, chainId)) {
  const address = getAddress(contracts.Token, chainId)
  // ...
}

fetchTokenInfo

Reads on-chain ERC-20 metadata from a token contract address. Fetches the standard fields (name, symbol, decimals, totalSupply) and optionally reads owner and paused if the contract supports them.

import { fetchTokenInfo } from '@web3marketlabs/sdk'

Signature

async function fetchTokenInfo(
  address: `0x${string}`,
  chainId: number,
  rpcUrl?: string,
): Promise<TokenInfo>

Parameters

ParameterTypeDescription
address*`0x${string}`The ERC-20 token contract address.
Example: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
chainId*numberThe numeric chain ID where the token is deployed.
Example: 1
rpcUrlstringOptional custom RPC URL. If omitted, uses the chain's default RPC.

TokenInfo Type

interface TokenInfo {
  address: string
  name: string
  symbol: string
  decimals: number
  totalSupply: string
  owner?: string       // Only present if the contract has an owner() function
  paused?: boolean     // Only present if the contract has a paused() function
}

The totalSupply field is returned as a string (not bigint) for serialization convenience. The owner and paused fields are optional and will be undefined if the contract does not implement those functions — their reads use Promise.allSettled so failures are silently ignored.

Example

import { fetchTokenInfo } from '@web3marketlabs/sdk'
 
const info = await fetchTokenInfo(
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  1,
)
 
console.log(info.name)         // 'USD Coin'
console.log(info.symbol)       // 'USDC'
console.log(info.decimals)     // 6
console.log(info.totalSupply)  // '40000000000000000' (as string)
console.log(info.owner)        // '0x...' or undefined
console.log(info.paused)       // true/false or undefined

Source

  • Address utilities: @web3marketlabs/sdk — src/addresses.ts
  • Token fetcher: @web3marketlabs/sdk — src/token-fetcher.ts
ABI UtilitiesIndex