@ensdomains/ensjs 4.1.2 → 5.0.0-alpha.0

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@ensdomains/ensjs",
-  "version": "4.1.2",
+  "version": "5.0.0-alpha.0",
   "description": "ENS javascript library for contract interaction",
   "type": "module",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "typings": "./dist/index.d.ts",
   "sideEffects": false,
@@ -20,8 +21,12 @@
       "default": "./dist/dns.js"
     },
     "./public": {
-      "types": "./dist/public.d.ts",
-      "default": "./dist/public.js"
+      "types": "./dist/exports/public.d.ts",
+      "default": "./dist/exports/public.js"
+    },
+    "./public/v2": {
+      "types": "./dist/exports/public/v2.d.ts",
+      "default": "./dist/exports/public/v2.js"
     },
     "./subgraph": {
       "types": "./dist/subgraph.d.ts",
@@ -32,8 +37,16 @@
       "default": "./dist/utils/index.js"
     },
     "./wallet": {
-      "types": "./dist/wallet.d.ts",
-      "default": "./dist/wallet.js"
+      "types": "./dist/exports/wallet.d.ts",
+      "default": "./dist/exports/wallet.js"
+    },
+    "./chain": {
+      "types": "./dist/exports/chain.d.ts",
+      "default": "./dist/exports/chain.js"
+    },
+    "./internal": {
+      "types": "./dist/exports/internal.d.ts",
+      "default": "./dist/exports/internal.js"
     },
     "./package.json": "./package.json"
   },
@@ -46,7 +59,7 @@
         "./dist/dns.d.ts"
       ],
       "public": [
-        "./dist/public.d.ts"
+        "./dist/exports/public.d.ts"
       ],
       "subgraph": [
         "./dist/subgraph.d.ts"
@@ -55,7 +68,13 @@
         "./dist/utils/index.d.ts"
       ],
       "wallet": [
-        "./dist/wallet.d.ts"
+        "./dist/exports/wallet.d.ts"
+      ],
+      "chain": [
+        "./dist/exports/chain.d.ts"
+      ],
+      "internal": [
+        "./dist/exports/internal.d.ts"
       ]
     }
   },
@@ -70,13 +89,12 @@
   "license": "MIT",
   "dependencies": {
     "@adraffy/ens-normalize": "1.10.1",
-    "@ensdomains/address-encoder": "1.1.3",
+    "@ensdomains/address-encoder": "1.1.1",
     "@ensdomains/content-hash": "3.1.0-rc.1",
     "@ensdomains/dnsprovejs": "^0.5.1",
-    "abitype": "^1.0.0",
     "dns-packet": "^5.3.1",
     "graphql": "^16.11.0",
-    "graphql-request": "7.1.2",
+    "graphql-request": "7.2.0",
     "pako": "^2.1.0",
     "ts-pattern": "^5.4.0"
   },
@@ -88,20 +106,17 @@
     "@nomicfoundation/hardhat-toolbox-viem": "^3.0.0",
     "@nomicfoundation/hardhat-viem": "2.0.6",
     "@openzeppelin/contracts": "^4.5.0",
-    "@openzeppelin/test-helpers": "^0.5.16",
     "@types/jsonfile": "^6.1.4",
     "@types/node": "^22.15.14",
     "@types/pako": "^2.0.0",
     "@vitest/coverage-v8": "^1.3.1",
     "cbor": "^8.1.0",
     "dotenv": "^16.0.0",
-    "ethers": "^5.7.2",
     "happy-dom": "^13.3.8",
     "hardhat": "2.24.1",
     "hardhat-abi-exporter": "^2.8.0",
     "hardhat-deploy": "^1.0.2",
     "jsonfile": "^6.1.0",
-    "multiformats": "^12.0.1",
     "solc": "^0.8.13",
     "ts-node": "^10.9.2",
     "typedoc": "^0.24.8",
@@ -123,7 +138,7 @@
     "test": "vitest --no-file-parallelism",
     "test:watch": "vitest --watch --no-file-parallelism",
     "clean": "rm -rf ./dist ./README.md ./LICENSE",
-    "lint": "eslint ./src/* --no-error-on-unmatched-pattern",
+    "lint": "biome check",
     "build": "tsc --project tsconfig.build.json",
     "tsn": "TS_NODE_PROJECT=tsconfig.node.json node --loader ts-node/esm",
     "prepublish": "pnpm build && cp ../../README.md ../../LICENSE ./",

package/src/actions/dns/getDnsImportData.ts

@@ -0,0 +1,109 @@
+import type { ProvableAnswer, SignedSet } from '@ensdomains/dnsprovejs'
+import type * as packet from 'dns-packet'
+import {
+  type Chain,
+  type Client,
+  getChainContractAddress,
+  type Hex,
+  toHex,
+} from 'viem'
+import { readContract } from 'viem/actions'
+import type { RequireClientContracts } from '../../clients/chain.js'
+import { dnssecImplVerifyRrSetSnippet } from '../../contracts/dnssecImpl.js'
+import { DnsNewerRecordTypeAvailableError } from '../../errors/dns.js'
+import { ASSERT_NO_TYPE_ERROR } from '../../types/internal.js'
+import type { Endpoint } from './types.js'
+
+export type GetDnsImportDataParameters = {
+  /** Name to prepare for DNS import */
+  name: string
+  /** An RFC-1035 compatible DNS endpoint to use (default: `https://cloudflare-dns.com/dns-query`) */
+  endpoint?: Endpoint
+}
+
+export type GetDnsImportDataReturnType = RrSetWithSig[]
+
+export type GetDnsImportDataErrorType = DnsNewerRecordTypeAvailableError | Error
+
+export type RrSetWithSig = {
+  rrset: Hex
+  sig: Hex
+}
+
+// Compares two serial numbers using RFC1982 serial number math.
+const serialNumberGt = (i1: number, i2: number): boolean =>
+  (i1 < i2 && i2 - i1 > 0x7fffffff) || (i1 > i2 && i1 - i2 < 0x7fffffff)
+
+const encodeProofs = (
+  proofs: SignedSet<packet.Ds | packet.Dnskey | packet.Rtxt>[],
+): RrSetWithSig[] =>
+  proofs.map((proof) => ({
+    rrset: toHex(proof.toWire(true)),
+    sig: toHex(proof.signature.data.signature),
+  }))
+
+/**
+ * Gets DNS import data, used for `importDnsName()`
+ * @param client - {@link Client}
+ * @param parameters - {@link GetDnsImportDataParameters}
+ * @returns DNS import data object, used for proving the value of the `_ens` TXT record
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getDnsImportData } from '@ensdomains/ensjs/dns'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const data = await getDnsImportData(client, {
+ *   name: 'example.eth',
+ * })
+ */
+export async function getDnsImportData<_chain extends Chain>(
+  client: RequireClientContracts<_chain, 'ensDnssecImpl'>,
+  {
+    name,
+    endpoint = 'https://cloudflare-dns.com/dns-query',
+  }: GetDnsImportDataParameters,
+): Promise<GetDnsImportDataReturnType> {
+  ASSERT_NO_TYPE_ERROR(client)
+  const { DNSProver } = await import('@ensdomains/dnsprovejs')
+  const prover = DNSProver.create(endpoint)
+  const result = (await prover.queryWithProof(
+    'TXT',
+    `_ens.${name}`,
+  )) as ProvableAnswer<packet.Rtxt>
+
+  const allProofs = (
+    result.proofs as SignedSet<packet.Ds | packet.Dnskey | packet.Rtxt>[]
+  ).concat([result.answer])
+
+  const rrsets = encodeProofs(allProofs)
+
+  const [onchainRrData, inception] = await readContract(client, {
+    abi: dnssecImplVerifyRrSetSnippet,
+    address: getChainContractAddress({
+      chain: client.chain,
+      contract: 'ensDnssecImpl',
+    }),
+    functionName: 'verifyRRSet',
+    args: [rrsets],
+  })
+
+  const lastProof = allProofs[allProofs.length - 1]
+  if (serialNumberGt(inception, lastProof.signature.data.inception))
+    throw new DnsNewerRecordTypeAvailableError({
+      typeCovered: lastProof.signature.data.typeCovered,
+      signatureName: lastProof.signature.name,
+      onchainInception: inception,
+      dnsInception: lastProof.signature.data.inception,
+    })
+
+  if (toHex(lastProof.toWire(false)) !== onchainRrData)
+    throw new Error('Mismatched proof data')
+
+  return rrsets
+}

package/src/actions/dns/getDnsOffchainData.ts

@@ -0,0 +1,169 @@
+import { type Address, type Chain, isAddress } from 'viem'
+import type { RequireClientContracts } from '../../clients/chain.js'
+import {
+  DnsDnssecVerificationFailedError,
+  DnsDnssecWildcardExpansionError,
+  DnsInvalidTxtRecordError,
+  DnsNoTxtRecordError,
+  DnsResponseStatusError,
+} from '../../errors/dns.js'
+import { UnsupportedNameTypeError } from '../../errors/general.js'
+import { getDnsTxtRecords } from '../../utils/dns/getDnsTxtRecords.js'
+import {
+  DnsRecordType,
+  type DnsResponseItem,
+  DnsResponseStatus,
+} from '../../utils/dns/misc.js'
+import { getNameType } from '../../utils/name/getNameType.js'
+import { getAddressRecord } from '../public/getAddressRecord.js'
+import type { Endpoint } from './types.js'
+
+export type GetDnsOffchainDataParameters = {
+  /** Name to get the offchain data for */
+  name: string
+  /** An RFC-1035 compatible DNS endpoint to use (default: `https://cloudflare-dns.com/dns-query`) */
+  endpoint?: Endpoint
+  /** Whether or not to throw errors */
+  strict?: boolean
+}
+
+export type GetDnsOffchainDataReturnType = {
+  resolverAddress: Address
+  extraData: string | null
+} | null
+
+export type GetDnsOffchainDataErrorType =
+  | DnsDnssecVerificationFailedError
+  | DnsDnssecWildcardExpansionError
+  | DnsInvalidTxtRecordError
+  | DnsNoTxtRecordError
+  | DnsResponseStatusError
+  | UnsupportedNameTypeError
+  | Error
+
+type ValidTextRecord = {
+  isValid: true
+  resolverAddress: Address
+  extraData: string | null
+}
+type InvalidTextRecord = { isValid: false; recordData: string }
+
+async function checkValidEnsTxtRecord<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  record: DnsResponseItem,
+): Promise<InvalidTextRecord | ValidTextRecord | null> {
+  if (record.type !== DnsRecordType.TXT) return null
+  if (!record.data.startsWith('"ENS1 ')) return null
+
+  const unwrappedRecordData = record.data.replace(/^"(.*)"$/g, '$1')
+
+  const resolverAndExtraData = unwrappedRecordData.slice(5)
+  const splitIndex = resolverAndExtraData.indexOf(' ')
+  const resolverNameOrAddress =
+    splitIndex === -1
+      ? resolverAndExtraData
+      : resolverAndExtraData.slice(0, splitIndex)
+  const extraData =
+    splitIndex === -1 ? null : resolverAndExtraData.slice(splitIndex + 1)
+
+  if (isAddress(resolverNameOrAddress))
+    return { isValid: true, resolverAddress: resolverNameOrAddress, extraData }
+
+  const resolverAddress = await getAddressRecord(client, {
+    name: resolverNameOrAddress,
+    // force no ccip-read, since dnsregistrar doesn't allow resolvers with ccip-read addresses
+    gatewayUrls: [],
+  }).catch(() => null) // if ccip-read is attempted, an error will be thrown. we can just ignore it
+
+  if (resolverAddress)
+    return {
+      isValid: true,
+      resolverAddress: resolverAddress.value as Address,
+      extraData,
+    }
+
+  return { isValid: false, recordData: unwrappedRecordData }
+}
+
+/**
+ * Gets the DNS offchain data for a name, via DNS record lookup
+ * @param client - {@link Client}
+ * @param parameters - {@link GetDnsOffchainDataParameters}
+ * @returns Resolver address and extra data, or null. {@link GetDnsOffchainDataReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getDnsOffchainData } from '@ensdomains/ensjs/dns'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const data = await getDnsOffchainData(client, {
+ *   name: 'ethleaderboard.xyz',
+ * })
+ */
+export async function getDnsOffchainData<chain extends Chain>(
+  client: RequireClientContracts<chain, 'ensUniversalResolver'>,
+  { name, endpoint, strict }: GetDnsOffchainDataParameters,
+): Promise<GetDnsOffchainDataReturnType> {
+  const nameType = getNameType(name)
+
+  if (nameType !== 'other-2ld' && nameType !== 'other-subname')
+    throw new UnsupportedNameTypeError({
+      nameType,
+      supportedNameTypes: ['other-2ld', 'other-subname'],
+    })
+
+  try {
+    const response = await getDnsTxtRecords({ name, endpoint })
+
+    if (response.Status !== DnsResponseStatus.NOERROR)
+      throw new DnsResponseStatusError({
+        responseStatus: DnsResponseStatus[response.Status],
+      })
+
+    if (response.AD === false)
+      throw new DnsDnssecVerificationFailedError({ record: undefined })
+
+    if (!response.Answer?.length) throw new DnsNoTxtRecordError()
+
+    const labels = name.split('.')
+    const rrsigRecord = response.Answer.find((record) => {
+      if (record.type !== DnsRecordType.RRSIG) return false
+      if (record.name !== name) return false
+      if (!record.data.startsWith('TXT')) return false
+      const [, , labelCount] = record.data.split(' ')
+      // mismatching label count implies wildcard expansion, which is not supported
+      return Number(labelCount) === labels.length
+    })
+
+    if (!rrsigRecord) throw new DnsDnssecWildcardExpansionError()
+
+    const ensTxtRecords = await Promise.all(
+      response.Answer.map((record) => checkValidEnsTxtRecord(client, record)),
+    )
+
+    const validRecord = ensTxtRecords.find(
+      (record): record is ValidTextRecord => record?.isValid === true,
+    )
+    if (validRecord)
+      return {
+        resolverAddress: validRecord.resolverAddress,
+        extraData: validRecord.extraData,
+      }
+
+    const invalidRecord = ensTxtRecords.find(
+      (record): record is InvalidTextRecord => record?.isValid === false,
+    )
+    if (invalidRecord)
+      throw new DnsInvalidTxtRecordError({ record: invalidRecord.recordData })
+
+    throw new DnsNoTxtRecordError()
+  } catch (error) {
+    if (!strict) return null
+    throw error
+  }
+}

package/src/actions/dns/getDnsOwner.ts

@@ -0,0 +1,96 @@
+import { type Address, getAddress } from 'viem'
+import {
+  DnsDnssecVerificationFailedError,
+  DnsInvalidAddressChecksumError,
+  DnsInvalidTxtRecordError,
+  DnsNoTxtRecordError,
+  DnsResponseStatusError,
+} from '../../errors/dns.js'
+import { UnsupportedNameTypeError } from '../../errors/general.js'
+import { getDnsTxtRecords } from '../../utils/dns/getDnsTxtRecords.js'
+import { DnsRecordType, DnsResponseStatus } from '../../utils/dns/misc.js'
+import { getNameType } from '../../utils/name/getNameType.js'
+import type { Endpoint } from './types.js'
+
+export type GetDnsOwnerParameters = {
+  /** Name to get the owner for */
+  name: string
+  /** An RFC-1035 compatible DNS endpoint to use (default: `https://cloudflare-dns.com/dns-query`) */
+  endpoint?: Endpoint
+  /** Whether or not to throw errors */
+  strict?: boolean
+}
+
+export type GetDnsOwnerReturnType = Address | null
+
+export type GetDnsOwnerErrorType =
+  | DnsDnssecVerificationFailedError
+  | DnsInvalidAddressChecksumError
+  | DnsInvalidTxtRecordError
+  | DnsNoTxtRecordError
+  | DnsResponseStatusError
+  | UnsupportedNameTypeError
+  | Error
+
+/**
+ * Gets the DNS owner of a name, via DNS record lookup
+ * @param parameters - {@link GetDnsOwnerParameters}
+ * @returns Address of DNS owner. {@link GetDnsOwnerReturnType}
+ *
+ * @example
+ * import { getDnsOwner } from '@ensdomains/ensjs/dns'
+ *
+ * const owner = await getDnsOwner({ name: 'ens.domains' })
+ * // '0xb8c2C29ee19D8307cb7255e1Cd9CbDE883A267d5'
+ */
+export async function getDnsOwner({
+  name,
+  endpoint,
+  strict,
+}: GetDnsOwnerParameters): Promise<GetDnsOwnerReturnType> {
+  const nameType = getNameType(name)
+
+  if (nameType !== 'other-2ld')
+    throw new UnsupportedNameTypeError({
+      nameType,
+      supportedNameTypes: ['other-2ld'],
+    })
+
+  try {
+    const response = await getDnsTxtRecords({ name: `_ens.${name}`, endpoint })
+
+    if (response.Status !== DnsResponseStatus.NOERROR)
+      throw new DnsResponseStatusError({
+        responseStatus: DnsResponseStatus[response.Status],
+      })
+
+    const addressRecord = response.Answer?.find(
+      (record) => record.type === DnsRecordType.TXT,
+    )
+    const unwrappedAddressRecord = addressRecord?.data?.replace(
+      /^"(.*)"$/g,
+      '$1',
+    )
+
+    if (response.AD === false)
+      throw new DnsDnssecVerificationFailedError({
+        record: unwrappedAddressRecord,
+      })
+
+    if (!addressRecord?.data) throw new DnsNoTxtRecordError()
+
+    if (!unwrappedAddressRecord?.match(/^a=0x[a-fA-F0-9]{40}$/g))
+      throw new DnsInvalidTxtRecordError({ record: unwrappedAddressRecord! })
+
+    const address = unwrappedAddressRecord?.slice(2)
+    const checksumAddress = getAddress(address)
+
+    if (address !== checksumAddress)
+      throw new DnsInvalidAddressChecksumError({ address })
+
+    return checksumAddress
+  } catch (error) {
+    if (!strict) return null
+    throw error
+  }
+}

package/src/actions/dns/importDnsName.ts

@@ -0,0 +1,175 @@
+import {
+  type Account,
+  type Address,
+  type Client,
+  encodeFunctionData,
+  getChainContractAddress,
+  type Hash,
+  type SendTransactionParameters,
+  type Transport,
+  toHex,
+} from 'viem'
+import { sendTransaction } from 'viem/actions'
+import { packetToBytes } from 'viem/ens'
+import type { ChainWithEns } from '../../clients/chain.js'
+import {
+  dnsRegistrarProveAndClaimSnippet,
+  dnsRegistrarProveAndClaimWithResolverSnippet,
+} from '../../contracts/dnsRegistrar.js'
+import { AdditionalParameterSpecifiedError } from '../../errors/general.js'
+import type {
+  Prettify,
+  SimpleTransactionRequest,
+  WriteTransactionParameters,
+} from '../../types/index.js'
+import type { GetDnsImportDataReturnType } from './getDnsImportData.js'
+
+type BaseImportDnsNameDataParameters = {
+  /** Name to import */
+  name: string
+  /** Data returned from `getDnsImportData()` */
+  dnsImportData: GetDnsImportDataReturnType
+  /** Address to claim the name for */
+  address?: Address
+  /** Address of the resolver to use (default: `ensPublicResolver`) */
+  resolverAddress?: Address
+}
+
+type NoResolverImportDnsNameDataParameters = {
+  address?: never
+  resolverAddress?: never
+}
+
+type ResolverImportDnsNameDataParameters = {
+  address: Address
+  resolverAddress?: Address
+}
+
+export type ImportDnsNameDataParameters = BaseImportDnsNameDataParameters &
+  (NoResolverImportDnsNameDataParameters | ResolverImportDnsNameDataParameters)
+
+export type ImportDnsNameDataReturnType = SimpleTransactionRequest
+
+export type ImportDnsNameParameters<
+  TChain extends ChainWithEns,
+  TAccount extends Account | undefined,
+  TChainOverride extends ChainWithEns | undefined,
+> = Prettify<
+  ImportDnsNameDataParameters &
+    WriteTransactionParameters<TChain, TAccount, TChainOverride>
+>
+
+export type ImportDnsNameReturnType = Hash
+
+export type ImportDnsNameErrorType = AdditionalParameterSpecifiedError | Error
+
+export const makeFunctionData = <
+  TChain extends ChainWithEns,
+  TAccount extends Account | undefined,
+>(
+  wallet: Client<Transport, TChain, TAccount>,
+  {
+    name,
+    dnsImportData,
+    address,
+    resolverAddress,
+  }: ImportDnsNameDataParameters,
+): ImportDnsNameDataReturnType => {
+  const hexEncodedName = toHex(packetToBytes(name))
+  const dnsRegistrarAddress = getChainContractAddress({
+    chain: wallet.chain,
+    contract: 'ensDnsRegistrar',
+  })
+
+  if (!address) {
+    if (resolverAddress)
+      throw new AdditionalParameterSpecifiedError({
+        parameter: 'resolverAddress',
+        allowedParameters: ['name', 'dnsImportData'],
+        details:
+          'resolverAddress cannot be specified when claiming without an address',
+      })
+    return {
+      to: dnsRegistrarAddress,
+      data: encodeFunctionData({
+        abi: dnsRegistrarProveAndClaimSnippet,
+        functionName: 'proveAndClaim',
+        args: [hexEncodedName, dnsImportData],
+      }),
+    }
+  }
+
+  const resolverAddress_ =
+    resolverAddress ||
+    getChainContractAddress({
+      chain: wallet.chain,
+      contract: 'ensPublicResolver',
+    })
+
+  return {
+    to: dnsRegistrarAddress,
+    data: encodeFunctionData({
+      abi: dnsRegistrarProveAndClaimWithResolverSnippet,
+      functionName: 'proveAndClaimWithResolver',
+      args: [hexEncodedName, dnsImportData, resolverAddress_, address],
+    }),
+  }
+}
+
+/**
+ * Creates a transaction to import a DNS name to ENS.
+ * @param wallet - {@link ClientWithAccount}
+ * @param parameters - {@link ImportDnsNameParameters}
+ * @returns A transaction hash. {@link ImportDnsNameReturnType}
+ *
+ * @example
+ * import { createPublicClient, createWalletClient, http, custom } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getDnsImportData, importDnsName } from '@ensdomains/ensjs/dns'
+ *
+ * const mainnetWithEns = addEnsContracts(mainnet)
+ * const client = createPublicClient({
+ *   chain: mainnetWithEns,
+ *   transport: http(),
+ * })
+ * const wallet = createWalletClient({
+ *   chain: mainnetWithEns,
+ *   transport: custom(window.ethereum),
+ * })
+ * const dnsImportData = await getDnsImportData(client, {
+ *   name: 'example.com',
+ * })
+ * const hash = await importDnsName(wallet, {
+ *   name: 'example.com',
+ *   dnsImportData,
+ * })
+ */
+export async function importDnsName<
+  TChain extends ChainWithEns,
+  TAccount extends Account | undefined,
+  TChainOverride extends ChainWithEns | undefined = ChainWithEns,
+>(
+  wallet: Client<Transport, TChain, TAccount>,
+  {
+    name,
+    address,
+    dnsImportData,
+    resolverAddress,
+    ...txArgs
+  }: ImportDnsNameParameters<TChain, TAccount, TChainOverride>,
+): Promise<ImportDnsNameReturnType> {
+  const data = makeFunctionData(wallet, {
+    name,
+    address,
+    dnsImportData,
+    resolverAddress,
+  } as ImportDnsNameDataParameters)
+  const writeArgs = {
+    ...data,
+    ...txArgs,
+  } as SendTransactionParameters<TChain, TAccount, TChainOverride>
+  return sendTransaction(wallet, writeArgs)
+}
+
+importDnsName.makeFunctionData = makeFunctionData