@ensdomains/ensjs 4.1.1 → 5.0.0-alpha.0

package/src/actions/public/getName.ts

@@ -0,0 +1,164 @@
+import { evmChainIdToCoinType } from '@ensdomains/address-encoder/utils'
+import type {
+  Address,
+  Chain,
+  GetAddressErrorType,
+  GetChainContractAddressErrorType,
+  ReadContractErrorType,
+  ToHexErrorType,
+} from 'viem'
+import { readContract } from 'viem/actions'
+import type { PacketToBytesErrorType } from 'viem/ens'
+import { getAction } from 'viem/utils'
+import {
+  getChainContractAddress,
+  type RequireClientContracts,
+} from '../../clients/chain.js'
+import {
+  universalResolverReverseSnippet,
+  universalResolverReverseWithGatewaysSnippet,
+} from '../../contracts/universalResolver.js'
+import type { ErrorType } from '../../errors/utils.js'
+import { ASSERT_NO_TYPE_ERROR } from '../../types/internal.js'
+import { isNullUniversalResolverError } from '../../utils/errors/isNullUniversalResolverError.js'
+import { parseReverseAddressMismatchError } from '../../utils/errors/parseReverseAddressMismatchError.js'
+import {
+  type NormalizeErrorType,
+  normalize,
+} from '../../utils/name/normalize.js'
+import { nullableAddress } from '../../utils/nullableAddress.js'
+
+type GetNameCoinTypeParameters = {
+  /** Coin type to use for reverse resolution */
+  coinType?: number
+  chainId?: never
+}
+
+type GetNameChainIdParameters = {
+  /** Chain ID to use for reverse resolution */
+  chainId?: number
+  coinType?: never
+}
+
+export type GetNameParameters = {
+  /** Address to get name for */
+  address: Address
+  /** Whether or not to allow mismatched forward resolution */
+  allowMismatch?: boolean
+  /** Whether or not to allow unnormalized name results (UNSAFE) */
+  allowUnnormalized?: boolean
+  /** Whether or not to throw decoding errors */
+  strict?: boolean
+  /** Batch gateway URLs to use for resolving CCIP-read requests. */
+  gatewayUrls?: string[]
+} & (GetNameCoinTypeParameters | GetNameChainIdParameters)
+
+export type GetNameReturnType = {
+  /** Primary name for address */
+  name: string
+  /** Indicates if forward resolution for name matches address */
+  match: boolean
+  /** Indicates if name is normalized */
+  normalized: boolean
+  /** Resolver address for reverse node */
+  reverseResolverAddress: Address | null
+  /** Resolver address for resolved name */
+  resolverAddress: Address | null
+} | null
+
+export type GetNameErrorType =
+  | ReadContractErrorType
+  | GetChainContractAddressErrorType
+  | ToHexErrorType
+  | PacketToBytesErrorType
+  | GetAddressErrorType
+  | NormalizeErrorType
+  | ErrorType
+
+/**
+ * Gets the primary name for an address
+ * @param client - {@link Client}
+ * @param parameters - {@link GetNameParameters}
+ * @returns Name data object, or `null` if no primary name is set. {@link GetNameReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getName } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getName(client, { address: '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5' })
+ * // { name: 'nick.eth', match: true, reverseResolverAddress: '0xa2c122be93b0074270ebee7f6b7292c7deb45047', resolverAddress: '0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41' }
+ */
+export async function getName<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  {
+    address,
+    allowUnnormalized,
+    strict,
+    gatewayUrls,
+    chainId,
+    coinType,
+    allowMismatch,
+  }: GetNameParameters,
+): Promise<GetNameReturnType> {
+  ASSERT_NO_TYPE_ERROR(client)
+  const readContractAction = getAction(client, readContract, 'readContract')
+
+  const parameters = {
+    address: getChainContractAddress({
+      chain: client.chain,
+      contract: 'ensUniversalResolver',
+    }),
+    abi: universalResolverReverseSnippet,
+    functionName: 'reverseWithGateways',
+    args: [address, chainId ? evmChainIdToCoinType(chainId) : coinType || 60n],
+  } as const
+
+  let unnormalisedName: string | null = null
+  let resolverAddress: Address | null = null
+  let reverseResolverAddress: Address | null = null
+  let match = true
+
+  try {
+    const [name, resolver, reverseResolver] = Array.isArray(gatewayUrls)
+      ? await readContractAction({
+          ...parameters,
+          abi: universalResolverReverseWithGatewaysSnippet,
+          args: [...parameters.args, gatewayUrls] as const,
+        })
+      : await readContractAction({ ...parameters, functionName: 'reverse' })
+    if (!name) return null
+    unnormalisedName = name
+    resolverAddress = resolver
+    reverseResolverAddress = reverseResolver
+  } catch (error) {
+    if (strict) throw error
+    if (isNullUniversalResolverError(error)) return null
+    const errorArgs = parseReverseAddressMismatchError(error)
+    if (Array.isArray(errorArgs)) {
+      unnormalisedName = errorArgs[0]
+      if (allowMismatch) {
+        match = false
+      } else {
+        return null
+      }
+    } else throw error
+  }
+
+  const normalizedName = normalize(unnormalisedName!)
+  const nameMatch = unnormalisedName === normalizedName
+  if (!nameMatch && !allowUnnormalized) return null
+
+  return {
+    name: unnormalisedName!,
+    match,
+    normalized: nameMatch,
+    reverseResolverAddress: nullableAddress(reverseResolverAddress!),
+    resolverAddress: nullableAddress(resolverAddress!),
+  }
+}

package/src/actions/public/getOwner.ts

@@ -0,0 +1,278 @@
+import {
+  type Address,
+  type Chain,
+  type MulticallErrorType,
+  type NamehashErrorType,
+  namehash,
+  type ReadContractErrorType,
+  type ReadContractParameters,
+  type ReadContractReturnType,
+  zeroAddress,
+} from 'viem'
+import { multicall, readContract } from 'viem/actions'
+import { getAction } from 'viem/utils'
+import {
+  getChainContractAddress,
+  type RequireClientContracts,
+} from '../../clients/chain.js'
+import { ASSERT_NO_TYPE_ERROR } from '../../types/internal.js'
+import { isNullRegistrarOwnerOfError } from '../../utils/errors/isNullRegistrarOwnerOfError.js'
+
+import { checkIsDotEth } from '../../utils/name/validation.js'
+import { nullableAddress } from '../../utils/nullableAddress.js'
+import {
+  type GetContractSpecificOwnerParametersErrorType,
+  getContractSpecificOwnerParameters,
+  type OwnerContract,
+} from '../../utils/ownerFromContract.js'
+
+export type GetOwnerParameters<
+  contract extends OwnerContract | undefined = undefined,
+> = {
+  /** Name to get owner for */
+  name: string
+  /** Optional specific contract to get ownership value from */
+  contract?: contract
+}
+
+type BaseGetOwnerReturnType = {
+  /** Owner of the name */
+  owner?: Address | null
+  /** Registrant of the name (registrar owner) */
+  registrant?: Address | null
+  /** The contract level that the ownership is on */
+  ownershipLevel: 'registry' | 'registrar' | 'nameWrapper'
+}
+
+type RegistrarOnlyOwnership = {
+  owner?: never
+  registrant: Address
+  ownershipLevel: 'registrar'
+}
+
+type WrappedOwnership = {
+  owner: Address
+  registrant?: never
+  ownershipLevel: 'nameWrapper'
+}
+
+type UnwrappedEth2ldOwnership = {
+  registrant: Address | null
+  owner: Address
+  ownershipLevel: 'registrar'
+}
+
+type UnwrappedOwnership = {
+  owner: Address
+  registrant?: never
+  ownershipLevel: 'registry'
+}
+
+export type GetOwnerReturnType<
+  contract extends OwnerContract | undefined = undefined,
+> =
+  | (BaseGetOwnerReturnType &
+      (contract extends 'registrar'
+        ? RegistrarOnlyOwnership
+        : contract extends 'nameWrapper'
+          ? WrappedOwnership
+          : contract extends 'registry'
+            ? UnwrappedOwnership
+            : WrappedOwnership | UnwrappedEth2ldOwnership | UnwrappedOwnership))
+  | null
+
+export type GetOwnerErrorType =
+  | NamehashErrorType
+  | ReadContractErrorType
+  | GetContractSpecificOwnerParametersErrorType
+  | MulticallErrorType
+
+/**
+ * Gets the owner(s) of a name.
+ * @param client - {@link Client}
+ * @param parameters - {@link GetOwnerParameters}
+ * @returns Owner data object, or `null` if no owners exist. {@link GetOwnerReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getOwner } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getOwner(client, { name: 'ens.eth' })
+ * // { owner: '0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9', registrant: '0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9', ownershipLevel: 'registrar }
+ */
+export async function getOwner<
+  chain extends Chain,
+  contract extends OwnerContract | undefined = undefined,
+>(
+  client: RequireClientContracts<
+    chain,
+    | 'ensNameWrapper'
+    | 'ensRegistry'
+    | 'ensBaseRegistrarImplementation'
+    | 'multicall3'
+  >,
+  { name, contract: contract_ }: GetOwnerParameters<contract>,
+): Promise<GetOwnerReturnType<contract>> {
+  ASSERT_NO_TYPE_ERROR(client)
+
+  const node = namehash(name)
+  const labels = name.split('.')
+
+  if (contract_ || labels.length === 1) {
+    const contract = contract_ || 'registry'
+    const readContractAction = getAction(client, readContract, 'readContract')
+    const params = getContractSpecificOwnerParameters(client.chain, {
+      contract,
+      node,
+      labels,
+    })
+    type OwnerParameters = Extract<typeof params, { functionName: 'owner' }>
+    type OwnerReturnType = ReadContractReturnType<
+      OwnerParameters['abi'],
+      'owner',
+      OwnerParameters['args']
+    >
+    type OwnerOfParameters = Extract<typeof params, { functionName: 'ownerOf' }>
+    type OwnerOfReturnType = ReadContractReturnType<
+      OwnerOfParameters['abi'],
+      'ownerOf',
+      OwnerOfParameters['args']
+    >
+    const result = (await readContractAction(
+      params as ReadContractParameters,
+    )) as OwnerReturnType | OwnerOfReturnType
+
+    if (result === zeroAddress) return null
+
+    if (contract === 'registrar')
+      return {
+        ownershipLevel: 'registrar',
+        registrant: result,
+      } as GetOwnerReturnType<contract>
+
+    return {
+      owner: result,
+      ownershipLevel: contract,
+    } as GetOwnerReturnType<contract>
+  }
+
+  const multicallAction = getAction(client, multicall, 'multicall')
+  const contractParameters = [
+    getContractSpecificOwnerParameters(client.chain, {
+      contract: 'registry',
+      node,
+      labels,
+    }),
+    getContractSpecificOwnerParameters(client.chain, {
+      contract: 'nameWrapper',
+      node,
+      labels,
+    }),
+  ] as const
+  const is2ldEth = checkIsDotEth(labels)
+  const [registryOwner, nameWrapperOwner, registrarOwner] = (
+    is2ldEth
+      ? await multicallAction({
+          contracts: [
+            ...contractParameters,
+            getContractSpecificOwnerParameters(client.chain, {
+              contract: 'registrar',
+              labels,
+            }),
+          ],
+          allowFailure: true,
+        })
+      : await multicallAction({
+          contracts: contractParameters,
+          allowFailure: true,
+        })
+  ).map((result, index) => {
+    if (result.error) {
+      if (index !== 2) throw result.error
+      if (!isNullRegistrarOwnerOfError(result.error)) throw result.error
+      return null
+    }
+    return nullableAddress(result.result)
+  })
+
+  const nameWrapperAddress = getChainContractAddress({
+    chain: client.chain,
+    contract: 'ensNameWrapper',
+  })
+
+  // check for only .eth names
+  if (labels[labels.length - 1] === 'eth') {
+    // if the owner on the registrar is the namewrapper, then the namewrapper owner is the owner
+    // there is no "registrant" for wrapped names
+    if (registrarOwner === nameWrapperAddress) {
+      return {
+        owner: nameWrapperOwner,
+        ownershipLevel: 'nameWrapper',
+      } as GetOwnerReturnType<contract>
+    }
+    // if there is a registrar owner, then it's not a subdomain but we have also passed the namewrapper clause
+    // this means that it's an unwrapped second-level name
+    // the registrant is the owner of the NFT
+    // the owner is the controller of the records
+    if (registrarOwner) {
+      return {
+        registrant: registrarOwner,
+        owner: registryOwner,
+        ownershipLevel: 'registrar',
+      } as GetOwnerReturnType<contract>
+    }
+    if (registryOwner !== null) {
+      // if there is no registrar owner, but the label length is two, then the domain is an expired 2LD .eth
+      // so we still want to return the ownership values
+      if (labels.length === 2) {
+        return {
+          registrant: null,
+          owner: registryOwner,
+          ownershipLevel: 'registrar',
+        } as GetOwnerReturnType<contract>
+      }
+      // this means that the subname is wrapped
+      if (registryOwner === nameWrapperAddress && nameWrapperOwner !== null) {
+        return {
+          owner: nameWrapperOwner,
+          ownershipLevel: 'nameWrapper',
+        } as GetOwnerReturnType<contract>
+      }
+      // unwrapped subnames do not have NFTs associated, so do not have a registrant
+      return {
+        owner: registryOwner,
+        ownershipLevel: 'registry',
+      } as GetOwnerReturnType<contract>
+    }
+    // .eth names with no registrar owner are either unregistered or expired
+    return null
+  }
+
+  // non .eth names inherit the owner from the registry
+  // there will only ever be an owner for non .eth names, not a registrant
+  // this is because for unwrapped names, there is no associated NFT
+  // and for wrapped names, owner and registrant are the same thing
+  if (registryOwner === nameWrapperAddress && nameWrapperOwner !== null) {
+    return {
+      owner: nameWrapperOwner,
+      ownershipLevel: 'nameWrapper',
+    } as GetOwnerReturnType<contract>
+  }
+
+  // for unwrapped non .eth names, the owner is the registry owner
+  if (registryOwner !== null) {
+    return {
+      owner: registryOwner,
+      ownershipLevel: 'registry',
+    } as GetOwnerReturnType<contract>
+  }
+
+  // for anything else, return
+  return null
+}

package/src/actions/public/getPrice.ts

@@ -0,0 +1,100 @@
+import type {
+  Chain,
+  GetChainContractAddressErrorType,
+  ReadContractErrorType,
+} from 'viem'
+import { readContract } from 'viem/actions'
+import { getAction } from 'viem/utils'
+import {
+  getChainContractAddress,
+  type RequireClientContracts,
+} from '../../clients/chain.js'
+import { l2EthRegistrarRentPriceSnippet } from '../../contracts/l2EthRegistrar.js'
+import { UnsupportedNameTypeError } from '../../errors/general.js'
+import { ASSERT_NO_TYPE_ERROR } from '../../types/internal.js'
+import { getNameType } from '../../utils/name/getNameType.js'
+
+export type GetPriceParameters = {
+  /** Name, or array of names, to get price for */
+  nameOrNames: string | string[]
+  /** Duration in seconds to get price for */
+  duration: bigint | number
+}
+
+export type GetPriceReturnType = {
+  /** Price base value */
+  base: bigint
+  /** Price premium */
+  premium: bigint
+}
+
+export type GetPriceErrorType =
+  | UnsupportedNameTypeError
+  | GetChainContractAddressErrorType
+  | ReadContractErrorType
+  | TypeError
+
+/**
+ * Gets the price of a name, or array of names, for a given duration.
+ * @param client - {@link Client}
+ * @param parameters - {@link GetPriceParameters}
+ * @returns Price data object. {@link GetPriceReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getPrice } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getPrice(client, { nameOrNames: 'ens.eth', duration: 31536000 })
+ * // { base: 352828971668930335n, premium: 0n }
+ */
+export async function getPrice<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensL2EthRegistrar'>,
+  { nameOrNames, duration }: GetPriceParameters,
+): Promise<GetPriceReturnType> {
+  ASSERT_NO_TYPE_ERROR(client)
+
+  const names = Array.isArray(nameOrNames) ? nameOrNames : [nameOrNames]
+
+  let totalBase = 0n
+  let totalPremium = 0n
+
+  const readContractAction = getAction(client, readContract, 'readContract')
+
+  // Process each name individually and aggregate the results
+  // TODO: not sure if this is the best way to do this, ask Jakob
+  for (const name of names) {
+    const labels = name.split('.')
+    const nameType = getNameType(name)
+
+    if (nameType !== 'eth-2ld' && nameType !== 'tld')
+      throw new UnsupportedNameTypeError({
+        nameType,
+        supportedNameTypes: ['eth-2ld', 'tld'],
+        details: 'Currently only the price of eth-2ld names can be fetched',
+      })
+
+    const result = await readContractAction({
+      address: getChainContractAddress({
+        chain: client.chain,
+        contract: 'ensL2EthRegistrar',
+      }),
+      abi: l2EthRegistrarRentPriceSnippet,
+      functionName: 'rentPrice',
+      args: [labels[0], BigInt(duration)],
+    })
+
+    totalBase += result.base
+    totalPremium += result.premium
+  }
+
+  return {
+    base: totalBase,
+    premium: totalPremium,
+  }
+}