@namehash/nameguard

NameGuard SDK

NameGuard is designed to inspect and prevent malicious use of Ethereum Name Service (ENS) names. It provides a comprehensive set of functionalities to check the normalization status of names, labels, and graphemes, conduct various safety checks on ENS names, and verify the authenticity of ".eth" names in NFTs.

NameGuard also supports multiple networks including Ethereum Mainnet and testnets.

⚠️ This SDK is BETA. Things will change based on the community feedback.

Features

• Normalization Status Checks: Determine if a name, label, or grapheme is normalized, unnormalized, or unknown.
• Safety Checks: Conduct various checks on ENS names for risks like impersonation, typing difficulty, and font support.
• ENS Name Verification: Verify the authenticity of ".eth" names associated with NFTs.
• Network-Specific Inspections: Customize inspections based on different Ethereum networks.

The @namehash/nameguard SDK provides full type-safety when working with the NameGuard API.

Install

Install NameGuard via npm, yarn or pnpm:

npm install @namehash/nameguard

Usage

Import nameguard:

import { nameguard } from "@namehash/nameguard";

Basic Inspections

Inspect a name:

const nameGuardReport = await nameguard.inspectName("nick.eth");

Batch Name Inspections

Inspect multiple names at once:

const names = ["vitalik.eth", "notrab.eth"];
const reports = await nameguard.bulkInspectNames(names);

Secure Primary Name Lookup

Lookup the secure primary ENS name for an Ethereum address:

const ethereumAddress = "0x..."; // replace with actual Ethereum address
const securePrimaryNameResult =
  await nameguard.getSecurePrimaryName(ethereumAddress);

This function is crucial for verifying the primary ENS name associated with an Ethereum address, ensuring its normalization status and checking for potential impersonation risks.

Verify ".eth" Names

Check if an NFT is associated with an authentic ".eth" name:

const fakeNameCheckResult = await nameguard.fakeEthNameCheck(
  contractAddress,
  tokenId,
);

Inspecting Graphemes

Inspect a single grapheme for various checks:

const graphemeReport = await nameguard.inspectGrapheme("𝒶");

Inspecting Labelhashes

Inspect a name based on a labelhash:

const labelhash = "0x..."; // replace with actual labelhash
const parentName = "eth"; // optional, defaults to 'eth'
const labelhashReport = await nameguard.inspectLabelhash(labelhash, {
  parent: parentName,
});

Inspecting Namehashes

Inspect the name associated with a specific namehash:

const namehash = "0x..."; // replace with actual namehash
const namehashReport = await nameguard.inspectNamehash(namehash);

These functions allow for a more granular level of inspection, particularly useful for applications that deal directly with ENS internals or require detailed analysis of the component parts of ENS names.

Custom client

You may have a different NameGuard API URL or network, you can instantiate a different client should you need to by importing createClient.

import { createClient } from "@namehash/nameguard";

const nameguard = createClient({
  url: "...",
  network: "sepolia",
});