ens-avatar

Avatar resolver library for both nodejs and browser.

Note!: ENS-Avatar >= 1.0.0 is only compatible with ethers v6. If your project is using v5, keep your ens-avatar on latest 0.x version.

Getting started

Prerequisites

• Have your web3 provider ready (web3.js, ethers.js)
• [Only for node env] Have jsdom installed.

And good to go!

Installation

# npm
npm i @ensdomains/ens-avatar
# yarn
yarn add @ensdomains/ens-avatar

Usage

import { StaticJsonRpcProvider } from '@ethersproject/providers';
import { AvatarResolver, utils as avtUtils } from '@ensdomains/ens-avatar';

// const { JSDOM } = require('jsdom'); on nodejs
// const jsdom = new JSDOM().window; on nodejs

const provider = new StaticJsonRpcProvider(
    ...
  );
...
async function getAvatar() {
    const resolver = new AvatarResolver(provider);
    const avatarURI = await resolver.getAvatar('tanrikulu.eth', { /* jsdomWindow: jsdom (on nodejs) */ });
    // avatarURI = https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR
}

async function getHeader() {
    const resolver = new AvatarResolver(provider);
    const headerURI = await resolver.getHeader('tanrikulu.eth', { /* jsdomWindow: jsdom (on nodejs) */ });
    // headerURI = https://ipfs.io/ipfs/QmRFnn6c9rj6NuHenFVyKXb6tuKxynAvGiw7yszQJ2EsjN
}

async function getAvatarMetadata() {
    const resolver = new AvatarResolver(provider);
    const avatarMetadata = await resolver.getMetadata('tanrikulu.eth');
    // avatarMetadata = { image: ... , uri: ... , name: ... , description: ... }
    const headerMetadata = await resolver.getMetadata('tanrikulu.eth', 'header');
    // headerMetadata = { image: ... , uri: ... , name: ... , description: ... }
    const avatarURI = avtUtils.getImageURI({ metadata: avatarMetadata /*, jsdomWindow: jsdom (on nodejs) */ });
    // avatarURI = https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR
}

Supported avatar specs

NFTs

• ERC721
• ERC1155

URIs

• HTTP
• Base64
• IPFS

Options

Cache (Default: Disabled)

const avt = new AvatarResolver(provider, { cache: 300 }); // 5 min response cache in memory

Custom IPFS Gateway (Default: https://ipfs.io)

const avt = new AvatarResolver(provider, { ipfs: 'https://dweb.link' });

Custom Arweave Gateway (Default: https://arweave.net)

const avt = new AvatarResolver(provider, { arweave: 'https://arweave.net' });

Marketplace Api Keys (Default: {})

const avt = new AvatarResolver(provider, {
  apiKey: {
    opensea: 'YOUR_API_KEY',
  },
});

URL DenyList (Default: [])

const avt = new AvatarResolver(provider, {
  urlDenyList: ['https://maliciouswebsite.com'],
});

Metadata Gas Limit (Default: 10000000)

Gas limit for the NFT contract's tokenURI() / uri() call. It bounds how large a string a contract can return (returned data costs gas), while leaving room for on-chain art that builds its metadata in the call.

const avt = new AvatarResolver(provider, { metadataGasLimit: 10_000_000 });

Inline SVG limits (Default: 1,000,000 bytes, 20,000 elements, 40,000 attributes)

Inline and data: SVG avatars are sanitized with DOMPurify, which builds a DOM node for every element and attribute. Before that happens, the decoded SVG is checked against a size limit, and a streaming parse (htmlparser2, which builds no tree) counts its elements and attributes, stopping at the first one over a limit. SVGs over any limit resolve to null.

const avt = new AvatarResolver(provider, {
  maxSvgBytes: 1_000_000,
  maxSvgElements: 20_000,
  maxSvgAttributes: 40_000,
});

Metadata limits

NFT and avatar-record metadata must be a JSON object of at most 1,000,000 bytes (MAX_METADATA_BYTES, checked before decoding and parsing; HTTP responses are capped with axios maxContentLength, which only the Node.js adapter enforces) and at most 1000 top-level properties (MAX_METADATA_PROPERTIES). Anything else is rejected with an error. Resolver-set fields (uri, host_meta, is_owner) can't be overridden by the metadata itself.

Demo

• Create .env file with INFURA_KEY env variable

• Build the library

• Node example

node example/node.js ENS_NAME

• Browser example

yarn build:demo
http-server example