@ensdomains/ensjs
Advanced tools
The ultimate ENS javascript library, with ethers.js under the hood.
ENSjs v3 is currently in the early development stage, meaning that the APIs are subject to change. We also use undeployed contracts under the hood, so this will not work on any mainnet/testnet where the contracts are not deployed.
Given the current development status, we're actively seeking feedback so feel free to create an issue or PR if you notice something!
If you are looking for documentation for version 2, it an be found here.
Install @ensdomains/ensjs, alongside ethers.
npm install @ensdomains/ensjs ethers
All that's needed to get started is an ethers provider instance. Once you create a new ENS instance, you can pass it in using setProvider.
import { ENS } from '@ensdomains/ensjs'
import { ethers } from 'ethers'
const provider = new ethers.providers.JsonRpcProvider(providerUrl)
const ENSInstance = new ENS()
await ENSInstance.setProvider(provider)
NOTE:
If using ENSjs with Node, you may need to pass the --experimental-specifier-resolution=node flag.
node --experimental-specifier-resolution=node ./index.js
The batch function is a large part of this library, and there are plenty of situations where you might want to use it.
Note that only functions with the GeneratedRawFunction type can be batched together.
/* Batch functions can be called like so, with the function as the first item in an array, with the following items being the function's arguments */
const batched = await ENSInstance.batch(
ENSInstance.getText.batch('test.eth', 'foo'),
ENSInstance.getAddr.batch('test.eth'),
ENSInstance.getOwner.batch('test.eth'),
)
/* The response is formatted like so:
[
response1,
response2,
response3,
...etc,
]
*/
If you want to use your own graph-node URI, such as a local graph-node URI, you can pass it through when creating a new ENS instance.
Alternatively, if you don't want to use The Graph at all you can pass through null.
import { ENS } from '@ensdomains/ensjs'
/* If you want to use a custom URI */
const ENSInstance = new ENS({
graphURI: 'http://localhost:8000/subgraphs/name/graphprotocol/ens',
})
/* If you want to disable The Graph queries */
const ENSInstance = new ENS({ graphURI: null })
If you want to use a specific provider to make a single call occasionally, you can easily do so.
import { ENS } from '@ensdomains/ensjs'
const ENSInstance = new ENS()
const callWithProvider = await ENSInstance.withProvider(otherProvider).getText(
'test.eth',
'foo',
)
You can fetch almost all information about an ENS name (or address) using getProfile. If an address is used as the first argument, it will fetch the primary name and give the same response as a name would. It will automatically get all the records for a name, as well as get the resolver address for the name. Specific records can also be used as an input, if you only want to get certain ones. If an address is used as an input alongside this, you also save 1 RPC call.
NOTE:
The profile function will always request an ETH addr record.
For names, this means the address will always at the top level of the returned object.
For addresses, this means the "match" property (a boolean value for matching reverse/forward resolution) will always be at the top level of the returned object.
/* Normal profile fetching */
const profile = await ENSInstance.getProfile('test.eth')
/* Profile fetching from an address */
const profile = await ENSInstance.getProfile(
'0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d',
)
/* Get all records of a specific type (or multiple) */
const profile = await ENSInstance.getProfile('test.eth', {
texts: true,
coinTypes: true,
contentHash: true,
})
/* Get specific records */
const profile = await ENSInstance.getProfile('test.eth', {
texts: ['foo'],
coinTypes: ['ETH'],
})
Returns:
type RecordItem = {
key: string | number
type: 'addr' | 'text' | 'contentHash'
coin?: string
addr?: string
value?: string
}
type ProfileReturn = {
address?: string // ONLY RETURNED AT TOP-LEVEL FOR NAME QUERIES
name?: string // ONLY RETURNED AT TOP-LEVEL FOR ADDRESS QUERIES
records: {
contentHash?: ContentHashObject | null
texts?: RecordItem[]
coinTypes?: RecordItem[]
}
resolverAddress: string
}
Getting the history for a name is very simple and can be done in two ways. Not all data can be immediately fetched for the history of an ENS name, which is why there is multiple methods for doing so. Text records do not contain the string value of the changed record, only the key. The value needs to be derived from fetching the individual transaction hash. This can potentially be very slow if the name has a long history.
/* Normal Fetching, requires a second function for more details */
const history = await ENSInstance.getHistory('test.eth')
/* Details helper for history */
/* You'll need to implement custom logic to get the index if you want to use that parameter, it's not currently done in the function */
const detail = await ENSInstance.getHistoryDetailForTransactionHash(
transactionHash,
optionalIndex,
)
/* Fetching with all details upfront */
const historyWithDetail = await ENSInstance.getHistoryWithDetail('test.eth')
The getOwner function returns not only an owner (and potentially a registrant), but also a ownershipLevel value.
This value essentially means the contract for the "real owner" of any given name. In most cases it means the NFT contract
of the name, but if there is no NFT then it's just the registry. This value is useful for input into the transferName
function, where a contract needs to be specified.
Wrapping names is very simple, you can wrap any name from the same function, with the exact contract to use being inferred. You can specify both the fuses and resolver address to use with the wrapped name, but it's entirely optional.
/* wrap a .eth name */
const tx = await ENSInstance.wrapName(
'test.eth', // Name to wrap
'0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d', // New owner of wrapped name
)
/* wrap any other name (e.g. a subname) */
const tx = await ENSInstance.wrapName(
'sub.test.eth',
'0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d',
)
Currently, some write functions have an options argument. While this may expand over time,
it currently just allows you to pass an address or index for an account array to ethers for specifying the signer of the transaction.
Raw functions are a crucial part of how ENSjs works. In the function file itself
a raw and decode function both need to be defined, with the export being an object with those properties.
This allows for the encoding and decoding of contract calls to be split, meaning that multiple calls can be batched together.
For calling a raw function by itself, the raw and decode functions are stitched together with a provider call. This is done
using importGenerator which is explained below.
The importGenerator function generates a wrapped function for any given input. The result of the wrapped function obfuscates the processing that ENSjs does, and exposes a cleaner API to the user/developer. The reason we do this is to:
raw and decode functions togetherThe contract manager is where all the contracts are dynamically loaded in and resolved based on the network. A new instance of ContractManager is created every time you switch providers.
The GQL manager is used as to separate the reliance of ENSjs from GQL. It only loads in GQL when it is needed, or not at all if specified in the constructor of the ENS class. Very simply, it just exposes the core functions needed for ENSjs which can then be accessed.
The initialProvider, and similarly checkInitialProvider are used when creating single-use class instances with withProvider.
It allows withProvider to act as a new ENS instance without having to await a promise, which simplifies the API.
checkInitialProvider is run on every function call given that it's extremely lightweight.
Utils can be imported at follows
import { encodeContenthash } from '@ensdomains/ensjs/utils/contentHash'
Gets the fuses for a specified wrapped name.
Input:
name: string
Output:
fuseObj: object
vulnerability: string
vulnerableNode: string | null
rawFuses: BigNumber
Gets the history for a specified name.
Input:
name: string
Output:
domain: array
registration: array
resolver: array
Gets the history for a specified name with details.
Input:
name: string
Output:
domain: array
registration: array
resolver: array
Gets the history details for a specified transaction hash.
Input:
hash: string
indexInTransaction: number?
Output:
key: string
value: string
Gets the primary name for a specified address.
Input:
address: string
Output:
name: string | null
match: boolean
Gets the owner of a specified name. See ownership levels for more details about the output.
Input:
name: string
Output:
owner: string
registrant: string?
ownershipLevel: string
Gets the profile of a specified name or address, or just certain records if specified.
Input:
nameOrAddress: string
options: object?
contentHash: boolean?texts: boolean? | string[]?
coinTypes: boolean? | string[]?
Output:
resolverAddress: string
records: object
contentHash: object? | null?
texts: array?
key: stringvalue: stringcoinTypes: array?
key: numbercoin: string
value: string
name: string?
address: string?
match: boolean?
Gets the resolver for a specified name.
Input:
name: string
Output:
Gets the content hash record for a specified name.
Input:
name: string
Output:
Gets a text record for a specified name.
Input:
name: string
key: string
Output:
Gets an address record for a specified name.
Input:
name: string
coinType: string? | number?
Output:
Creates a transaction to burn fuses on a specified wrapped name.
Input:
name: string
fusesToBurn: object
Output:
Creates a subname using the specified contract.
Input:
name: string
owner: string
contract: registry | nameWrapper
resolverAddress: string?
shouldWrap: boolean?
fuses: object?
Output:
Deletes a subname using the specified contract.
Input:
name: string
contract: registry | nameWrapper
Output:
Transfers a subname using the specified contract. Please note that transferring a wrapped name using this method will unwrap the name.
Input:
name: string
contract: registry | nameWrapper
address: string
Output:
Sets the primary name for a specified address.
Input:
name: string
address: string?
resolver: string?
Output:
Sets multiple records at once for the specified name.
Input:
name: string
records: object
contentHash: string?
texts: array?
key: string
value: string
coinTypes: array?
key: string
value: string
Output:
Sets the resolver for the specified name, using the specified contract.
Input:
name: string
contract: registry | nameWrapper
resolver: string?
Output:
Transfers a name, using the specified contract.
Input:
name: string
newOwner: string
contract: registry | nameWrapper | baseRegistrar
Output:
Wraps a name.
Input:
name: string
wrappedOwner: string
fuseOptions: object?
resolverAddress: string?
Output:
Unwraps a name.
Input:
name: string
newController: string
newRegistrant: string?
Output:
Wraps a function so it is directed to the universal resolver instead of the default public resolver.
Input:
name: string
data: string
Output:
data: string
resolver: string
Examples for universalWrapper can be found in getSpecificRecord.
Wraps multiple resolver calls so they are made into a single resolver multicall.
Input:
to: string
data: string
Output:
Examples for resolverMulticallWrapper can be found in getProfile.
FAQs
ENS javascript library for contract interaction
The npm package @ensdomains/ensjs receives a total of 18,214 weekly downloads. As such, @ensdomains/ensjs popularity was classified as popular.
We found that @ensdomains/ensjs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.