@ensdomains/ensjs 4.1.2 → 5.0.0-alpha.0

package/src/actions/public/getAbiRecord.ts

@@ -0,0 +1,72 @@
+import type { Chain, EncodeFunctionDataErrorType } from 'viem'
+import { encodeFunctionData, getAction } from 'viem/utils'
+import type { RequireClientContracts } from '../../clients/chain.js'
+import type { Prettify } from '../../types/index.js'
+import type { ExcludeTE } from '../../types/internal.js'
+import {
+  type DecodeAbiResultErrorType,
+  type DecodeAbiResultParameters,
+  type DecodeAbiResultReturnType,
+  decodeAbiResult,
+  type GetAbiParametersErrorType,
+  type GetAbiParametersParameters,
+  getAbiParameters,
+} from '../../utils/coders/getAbi.js'
+import {
+  type ResolveNameDataErrorType,
+  resolveNameData,
+} from './resolveNameData.js'
+
+export type GetAbiRecordParameters = Prettify<
+  GetAbiParametersParameters &
+    DecodeAbiResultParameters & {
+      /** Batch gateway URLs to use for resolving CCIP-read requests. */
+      gatewayUrls?: string[]
+    }
+>
+
+export type GetAbiRecordReturnType = DecodeAbiResultReturnType | null
+
+export type GetAbiRecordErrorType =
+  | ResolveNameDataErrorType
+  | EncodeFunctionDataErrorType
+  | GetAbiParametersErrorType
+  | DecodeAbiResultErrorType
+
+/**
+ * Gets the ABI record for a name
+ * @param client - {@link Client}
+ * @param parameters - {@link GetAbiRecordParameters}
+ * @returns ABI record for the name, or `null` if not found. {@link GetAbiRecordReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getAbiRecord } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getAbiRecord(client, { name: 'ens.eth' })
+ * // TODO: real example
+ */
+export async function getAbiRecord<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  { gatewayUrls, name, supportedContentTypes, strict }: GetAbiRecordParameters,
+): Promise<GetAbiRecordReturnType> {
+  const resolveNameDataAction = getAction(
+    client as ExcludeTE<typeof client>,
+    resolveNameData,
+    'resolveNameData',
+  )
+  const result = await resolveNameDataAction({
+    name,
+    data: encodeFunctionData(getAbiParameters({ name, supportedContentTypes })),
+    gatewayUrls,
+    strict,
+  })
+  if (!result) return null
+  return decodeAbiResult(result.resolvedData, { strict })
+}

package/src/actions/public/getAddressRecord.ts

@@ -0,0 +1,87 @@
+import type { Chain, EncodeFunctionDataErrorType } from 'viem'
+import { encodeFunctionData, getAction } from 'viem/utils'
+import type { RequireClientContracts } from '../../clients/chain.js'
+import type { Prettify } from '../../types/index.js'
+import type { ExcludeTE } from '../../types/internal.js'
+import {
+  type DecodeAddressResultErrorType,
+  type DecodeAddressResultParameters,
+  type DecodeAddressResultReturnType,
+  decodeAddressResult,
+  type GetAddressParametersErrorType,
+  type GetAddressParametersParameters,
+  getAddressParameters,
+} from '../../utils/coders/getAddress.js'
+import {
+  type ResolveNameDataErrorType,
+  resolveNameData,
+} from './resolveNameData.js'
+
+export type GetAddressRecordParameters<
+  coin extends string | number | undefined = undefined,
+> = Prettify<
+  GetAddressParametersParameters<coin> &
+    DecodeAddressResultParameters<coin> & {
+      /** Batch gateway URLs to use for resolving CCIP-read requests. */
+      gatewayUrls?: string[]
+    }
+>
+
+export type GetAddressRecordReturnType<
+  coin extends string | number | undefined = undefined,
+> = DecodeAddressResultReturnType<coin>
+
+export type GetAddressRecordErrorType =
+  | ResolveNameDataErrorType
+  | EncodeFunctionDataErrorType
+  | GetAddressParametersErrorType
+  | DecodeAddressResultErrorType
+
+/**
+ * Gets an address record for a name and specified coin
+ * @param client - {@link Client}
+ * @param parameters - {@link GetAddressRecordParameters}
+ * @returns Coin value object, or `null` if not found. {@link GetAddressRecordReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getAddressRecord } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getAddressRecord(client, { name: 'ens.eth', coin: 'ETH' })
+ * // { id: 60, name: 'ETH , value: '0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7' }
+ */
+export async function getAddressRecord<
+  chain extends Chain,
+  coin extends string | number | undefined = undefined,
+>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  {
+    gatewayUrls,
+    strict,
+    name,
+    bypassFormat,
+    coin,
+  }: GetAddressRecordParameters<coin>,
+): Promise<GetAddressRecordReturnType<coin>> {
+  const resolveNameDataAction = getAction(
+    client as ExcludeTE<typeof client>,
+    resolveNameData,
+    'resolveNameData',
+  )
+  const result = await resolveNameDataAction({
+    name,
+    data: encodeFunctionData(
+      getAddressParameters({ name, bypassFormat, coin }),
+    ),
+    gatewayUrls,
+    strict,
+  })
+  if (!result) return null
+  return decodeAddressResult(result.resolvedData, { strict, coin })
+}

package/src/actions/public/getAvailable.ts

@@ -0,0 +1,76 @@
+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 { l2EthRegistrarAvailableSnippet } from '../../contracts/l2EthRegistrar.js'
+import { UnsupportedNameTypeError } from '../../errors/general.js'
+import type { ErrorType } from '../../errors/utils.js'
+import { ASSERT_NO_TYPE_ERROR } from '../../types/internal.js'
+import { getNameType } from '../../utils/name/getNameType.js'
+
+export type GetAvailableParameters = {
+  /** Name to check availability for, only compatible for eth 2ld */
+  name: string
+}
+
+export type GetAvailableReturnType = boolean
+
+export type GetAvailableErrorType =
+  | UnsupportedNameTypeError
+  | ReadContractErrorType
+  | GetChainContractAddressErrorType
+  | ErrorType
+
+/**
+ * Gets the availability of a name to register
+ * @param client - {@link Client}
+ * @param parameters - {@link GetAvailableParameters}
+ * @returns Availability as boolean. {@link GetAvailableReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getAvailable } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getAvailable(client, { name: 'ens.eth' })
+ * // false
+ */
+export async function getAvailable<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensL2EthRegistrar'>,
+  { name }: GetAvailableParameters,
+): Promise<GetAvailableReturnType> {
+  const labels = name.split('.')
+  const nameType = getNameType(name)
+  ASSERT_NO_TYPE_ERROR(client)
+  if (nameType !== 'eth-2ld')
+    throw new UnsupportedNameTypeError({
+      nameType,
+      supportedNameTypes: ['eth-2ld'],
+      details: 'Currently only eth-2ld names can be checked for availability',
+    })
+
+  const readContractAction = getAction(client, readContract, 'readContract')
+
+  const result = await readContractAction({
+    address: getChainContractAddress({
+      chain: client.chain,
+      contract: 'ensL2EthRegistrar',
+    }),
+    abi: l2EthRegistrarAvailableSnippet,
+    functionName: 'available',
+    args: [labels[0]],
+  })
+  return result
+}

package/src/actions/public/getContentHashRecord.ts

@@ -0,0 +1,70 @@
+import type { Chain, EncodeFunctionDataErrorType } from 'viem'
+import { encodeFunctionData, getAction } from 'viem/utils'
+import type { RequireClientContracts } from '../../clients/chain.js'
+import type { Prettify } from '../../types/index.js'
+import type { ExcludeTE } from '../../types/internal.js'
+import {
+  type DecodeContentHashResultErrorType,
+  decodeContentHashResult,
+  type GetContentHashErrorType,
+  type GetContentHashParameters,
+  type GetContentHashReturnType,
+  getContentHashParameters,
+} from '../../utils/coders/getContentHash.js'
+import {
+  type ResolveNameDataErrorType,
+  resolveNameData,
+} from './resolveNameData.js'
+
+export type GetContentHashRecordParameters = Prettify<
+  GetContentHashParameters & {
+    /** Batch gateway URLs to use for resolving CCIP-read requests. */
+    gatewayUrls?: string[]
+  }
+>
+
+export type GetContentHashRecordReturnType = GetContentHashReturnType
+
+export type GetContentHashRecordErrorType =
+  | GetContentHashErrorType
+  | ResolveNameDataErrorType
+  | EncodeFunctionDataErrorType
+  | DecodeContentHashResultErrorType
+
+/**
+ * Gets the content hash record for a name
+ * @param client - {@link Client}
+ * @param parameters - {@link GetContentHashRecordParameters}
+ * @returns Content hash object, or `null` if not found. {@link GetContentHashRecordReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getContentHashRecord } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getContentHashRecord(client, { name: 'ens.eth' })
+ * // { protocolType: 'ipfs', decoded: 'k51qzi5uqu5djdczd6zw0grmo23j2vkj9uzvujencg15s5rlkq0ss4ivll8wqw' }
+ */
+export async function getContentHashRecord<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  { gatewayUrls, name, strict }: GetContentHashRecordParameters,
+): Promise<GetContentHashRecordReturnType> {
+  const resolveNameDataAction = getAction(
+    client as ExcludeTE<typeof client>,
+    resolveNameData,
+    'resolveNameData',
+  )
+  const result = await resolveNameDataAction({
+    name,
+    data: encodeFunctionData(getContentHashParameters({ name })),
+    gatewayUrls,
+    strict,
+  })
+  if (!result) return null
+  return decodeContentHashResult(result.resolvedData, { strict })
+}

package/src/actions/public/getCredentials.ts

@@ -0,0 +1,65 @@
+import type { Chain } from 'viem'
+import type { RequireClientContracts } from '../../clients/chain.js'
+import type { ErrorType } from '../../errors/utils.js'
+import type { Prettify } from '../../types/index.js'
+import {
+  type GetTextRecordErrorType,
+  type GetTextRecordParameters,
+  getTextRecord,
+} from './getTextRecord.js'
+
+export type GetCredentialsParameters = Prettify<
+  Omit<GetTextRecordParameters, 'key'>
+>
+
+export type GetCredentialsReturnType = ExternalCredential[] | null
+
+export type GetCredentialsErrorType = GetTextRecordErrorType | ErrorType
+
+export type ExternalCredential = {
+  url: string
+}
+
+const parseCredentials = (credentials: string[]) => {
+  const externalCredentials: ExternalCredential[] = []
+  for (const credential of credentials) {
+    if (URL.canParse(credential)) externalCredentials.push({ url: credential })
+  }
+
+  return externalCredentials
+}
+
+/**
+ * Gets credentials for a name.
+ * @param client - {@link Client}
+ * @param parameters - {@link GetCredentialsParameters}
+ * @returns Credentials, or null if none are found. {@link GetCredentialsReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getCredentials } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getCredentials(client, { name: 'ens.eth' })
+ * // [{ url: 'https://example.com' }]
+ */
+export async function getCredentials<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  { gatewayUrls, strict, name }: GetCredentialsParameters,
+): Promise<GetCredentialsReturnType> {
+  const result = await getTextRecord(client, {
+    name,
+    key: 'verifications',
+    gatewayUrls,
+    strict,
+  })
+  if (!result) return null
+
+  const credential = JSON.parse(result) as string[]
+  return parseCredentials(credential)
+}

package/src/actions/public/getExpiry.ts

@@ -0,0 +1,220 @@
+import {
+  type Address,
+  type Chain,
+  type GetChainContractAddressErrorType,
+  type LabelhashErrorType,
+  labelhash,
+  type MulticallErrorType,
+  type NamehashErrorType,
+  namehash,
+} from 'viem'
+import { multicall } from 'viem/actions'
+import { getAction } from 'viem/utils'
+import {
+  getChainContractAddress,
+  type RequireClientContracts,
+} from '../../clients/chain.js'
+import {
+  baseRegistrarGracePeriodSnippet,
+  baseRegistrarNameExpiresSnippet,
+} from '../../contracts/baseRegistrar.js'
+import { multicallGetCurrentBlockTimestampSnippet } from '../../contracts/multicall.js'
+import { nameWrapperGetDataSnippet } from '../../contracts/nameWrapper.js'
+import { registryOwnerSnippet } from '../../contracts/registry.js'
+import { UnsupportedNameTypeError } from '../../errors/general.js'
+import type { Prettify } from '../../types/index.js'
+import type { ExcludeTE } from '../../types/internal.js'
+import { getNameType } from '../../utils/name/getNameType.js'
+import { checkIsDotEth } from '../../utils/name/validation.js'
+
+type ContractOption = 'registrar' | 'nameWrapper' | 'l2Registrar'
+type ExpiryStatus = 'active' | 'expired' | 'gracePeriod'
+
+export type GetExpiryParameters = Prettify<{
+  /** Name to get expiry for */
+  name: string
+  /** Optional specific contract to use to get expiry */
+  contract?: ContractOption
+}>
+
+export type GetExpiryReturnType = Prettify<{
+  /** Expiry value */
+  expiry: bigint
+  /** Grace period value (in seconds) */
+  gracePeriod: number
+  /** Status of name */
+  status: ExpiryStatus
+} | null>
+
+export type GetExpiryErrorType =
+  | MulticallErrorType
+  | GetChainContractAddressErrorType
+  | NamehashErrorType
+  | LabelhashErrorType
+
+/**
+ * Gets the expiry for a name
+ * @param client - {@link Client}
+ * @param parameters - {@link GetExpiryParameters}
+ * @returns Expiry object, or `null` if no expiry. {@link GetExpiryReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getExpiry } from '@ensdomains/ensjs/public'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getExpiry(client, { name: 'ens.eth' })
+ * // { expiry: { date: Date, value: 1913933217n }, gracePeriod: 7776000, status: 'active' }
+ *
+ * // Using L2 registrar
+ * const l2Result = await getExpiry(client, { name: 'example.eth', contract: 'l2Registrar' })
+ */
+export async function getExpiry<chain extends Chain>(
+  client: RequireClientContracts<
+    chain,
+    | 'ensNameWrapper'
+    | 'ensBaseRegistrarImplementation'
+    | 'ensRegistry'
+    | 'multicall3'
+  >,
+  { name, contract: contractOption }: GetExpiryParameters,
+): Promise<GetExpiryReturnType> {
+  const chain = (client as ExcludeTE<typeof client>).chain
+  const labels = name.split('.')
+  const contract = (() => {
+    if (contractOption) {
+      if (
+        (contractOption === 'registrar' || contractOption === 'l2Registrar') &&
+        !checkIsDotEth(labels)
+      )
+        throw new UnsupportedNameTypeError({
+          nameType: getNameType(name),
+          supportedNameTypes: ['eth-2ld', 'tld'],
+          details:
+            'Only the expiry of eth-2ld names can be fetched when using the registrar or l2Registrar contract',
+        })
+      return contractOption
+    }
+    if (checkIsDotEth(labels)) return 'registrar'
+    return 'nameWrapper'
+  })()
+
+  const multicallAction = getAction(
+    client as ExcludeTE<typeof client>,
+    multicall,
+    'multicall',
+  )
+
+  const getCurrentBlockTimestampParameters = {
+    address: getChainContractAddress({
+      chain,
+      contract: 'multicall3',
+    }),
+    abi: multicallGetCurrentBlockTimestampSnippet,
+    functionName: 'getCurrentBlockTimestamp',
+  } as const
+
+  const [currentBlockTimestamp, expiry, gracePeriod] = await (async () => {
+    if (contract === 'nameWrapper') {
+      const [timestamp_, [, , expiry_]] = await multicallAction({
+        contracts: [
+          getCurrentBlockTimestampParameters,
+          {
+            address: getChainContractAddress({
+              chain,
+              contract: 'ensNameWrapper',
+            }),
+            abi: nameWrapperGetDataSnippet,
+            functionName: 'getData',
+            args: [BigInt(namehash(name))],
+          },
+        ],
+        allowFailure: false,
+      })
+      return [timestamp_, expiry_, 0n] as const
+    }
+
+    if (contract === 'l2Registrar') {
+      // For L2 registrars, we get the registry owner which should be the L2 registrar
+      // and query it for expiry information
+      const [timestamp_, registryOwner] = await multicallAction({
+        contracts: [
+          getCurrentBlockTimestampParameters,
+          {
+            address: getChainContractAddress({
+              chain,
+              contract: 'ensRegistry',
+            }),
+            abi: registryOwnerSnippet,
+            functionName: 'owner',
+            args: [namehash(name)],
+          },
+        ],
+        allowFailure: false,
+      })
+
+      // Now query the registry owner (L2 registrar) for expiry information
+      const [nameExpiry, gracePeriodValue] = await multicallAction({
+        contracts: [
+          {
+            address: registryOwner as Address,
+            abi: baseRegistrarNameExpiresSnippet,
+            functionName: 'nameExpires',
+            args: [BigInt(labelhash(labels[0]))],
+          },
+          {
+            address: registryOwner as Address,
+            abi: baseRegistrarGracePeriodSnippet,
+            functionName: 'GRACE_PERIOD',
+          },
+        ],
+        allowFailure: false,
+      })
+
+      return [timestamp_, nameExpiry, gracePeriodValue] as const
+    }
+
+    return await multicallAction({
+      contracts: [
+        getCurrentBlockTimestampParameters,
+        {
+          address: getChainContractAddress({
+            chain,
+            contract: 'ensBaseRegistrarImplementation',
+          }),
+          abi: baseRegistrarNameExpiresSnippet,
+          functionName: 'nameExpires',
+          args: [BigInt(labelhash(labels[0]))],
+        },
+        {
+          address: getChainContractAddress({
+            chain,
+            contract: 'ensBaseRegistrarImplementation',
+          }),
+          abi: baseRegistrarGracePeriodSnippet,
+          functionName: 'GRACE_PERIOD',
+        },
+      ],
+      allowFailure: false,
+    })
+  })()
+
+  if (expiry === 0n) return null
+
+  const status = (() => {
+    if (currentBlockTimestamp > expiry + gracePeriod) return 'expired'
+    if (currentBlockTimestamp > expiry) return 'gracePeriod'
+    return 'active'
+  })()
+
+  return {
+    expiry,
+    gracePeriod: Number(gracePeriod),
+    status,
+  }
+}