@fileverse/ens

Tiny ENS resolution helpers built on viem. Resolves an Ethereum mainnet address to its primary ENS name, with a memoized PublicClient per RPC URL so it's safe to call in hot paths.

Install

npm install @fileverse/ens

Usage

getAddressName(address, providerUrl)

Caller-friendly wrapper. Always resolves; never throws on bad input or network errors.

import { getAddressName } from "@fileverse/ens";

const result = await getAddressName(
  "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "https://mainnet.example/rpc",
);

// { name: "vitalik.eth", isEns: true, resolved: true }

Result shape:

| field | meaning | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | name | ENS name when found, otherwise the input address. | | isEns | true only when an ENS name was resolved. | | resolved | true when the lookup completed (hit or confirmed miss). Use this to decide whether to cache — false means invalid input or a thrown error. |

Throws only if providerUrl is empty.

resolveEnsAddress(address, providerUrl)

Thin wrapper over viem's getEnsName. Errors and invalid inputs propagate — use getAddressName if you want a safe shape.

import { resolveEnsAddress } from "@fileverse/ens";

const name = await resolveEnsAddress(address, providerUrl);
// string | null

getMainnetClient(url)

Returns a memoized viem mainnet PublicClient for the given RPC URL. One client per distinct URL, cached for the lifetime of the module.

import { getMainnetClient } from "@fileverse/ens";

const client = getMainnetClient("https://mainnet.example/rpc");

isAddress(value) / isHex(value)

Re-exported from viem so you can validate inputs without adding a separate viem import.

import { isAddress, isHex } from "@fileverse/ens";

isAddress("0xd8da6bf26964af9d7eed9e03e53415d37aa96045"); // true
isHex("0xdeadbeef"); // true

Scripts

• npm run build — type-check and build with Vite (Rolldown).
• npm run dev — Vite dev server.