@ensdomains/ensjs 3.0.0-alpha.9 → 3.0.0-beta.10

package/src/functions/subgraph/getNamesForAddress.ts

@@ -0,0 +1,364 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { gql } from 'graphql-request'
+import type { Address } from 'viem'
+import type { ClientWithEns } from '../../contracts/consts.js'
+import {
+  FilterKeyRequiredError,
+  InvalidFilterKeyError,
+  InvalidOrderByError,
+} from '../../errors/subgraph.js'
+import { EMPTY_ADDRESS, GRACE_PERIOD_SECONDS } from '../../utils/consts.js'
+import { createSubgraphClient } from './client.js'
+import type { DomainFilter } from './filters.js'
+import {
+  domainDetailsFragment,
+  registrationDetailsFragment,
+  wrappedDomainDetailsFragment,
+  type SubgraphDomain,
+} from './fragments.js'
+import { makeNameObject, type Name } from './utils.js'
+
+const supportedOwnerFilters = [
+  'owner',
+  'registrant',
+  'wrappedOwner',
+  'resolvedAddress',
+] as const
+
+type GetNamesForAddressOrderBy =
+  | 'expiryDate'
+  | 'name'
+  | 'labelName'
+  | 'createdAt'
+
+type GetNamesForAddressRelation = {
+  /** Names with registrant as address (default: true) */
+  registrant?: boolean
+  /** Names with owner as address (default: true) */
+  owner?: boolean
+  /** Names with wrapped owner as address (default: true) */
+  wrappedOwner?: boolean
+  /** Names with matching resolving address (default: true) */
+  resolvedAddress?: boolean
+}
+
+type GetNamesForAddressFilter = GetNamesForAddressRelation & {
+  /** Search string filter for subname label */
+  searchString?: string
+  /** Allows expired names to be included (default: false) */
+  allowExpired?: boolean
+  /** Allows reverse record nodes to be included (default: false) */
+  allowReverseRecord?: boolean
+  /** Allows deleted names to be included (default: false) */
+  allowDeleted?: boolean
+}
+
+export type GetNamesForAddressParameters = {
+  /** Address to get names for */
+  address: Address
+  /** Names to get, in relation to address */
+  filter?: GetNamesForAddressFilter
+  /** Parameter to order names by (default: name) */
+  orderBy?: GetNamesForAddressOrderBy
+  /** Direction to order names in (default: asc) */
+  orderDirection?: 'asc' | 'desc'
+  /** Previous page of names, used for pagination */
+  previousPage?: NameWithRelation[]
+  /** Page size (default: 100) */
+  pageSize?: number
+}
+
+export type NameWithRelation = Name & {
+  relation: GetNamesForAddressRelation
+}
+
+export type GetNamesForAddressReturnType = NameWithRelation[]
+
+type SubgraphResult = {
+  domains: SubgraphDomain[]
+}
+
+const getOrderByFilter = ({
+  orderBy,
+  orderDirection,
+  previousPage,
+}: Required<
+  Pick<
+    GetNamesForAddressParameters,
+    'orderBy' | 'orderDirection' | 'previousPage'
+  >
+>): DomainFilter => {
+  const lastDomain = previousPage[previousPage.length - 1]
+  const operator = orderDirection === 'asc' ? 'gt' : 'lt'
+
+  switch (orderBy) {
+    case 'expiryDate': {
+      let lastExpiryDate = lastDomain.expiryDate?.value
+        ? lastDomain.expiryDate.value / 1000
+        : 0
+      if (lastDomain.parentName === 'eth') {
+        lastExpiryDate += GRACE_PERIOD_SECONDS
+      }
+
+      if (orderDirection === 'asc' && lastExpiryDate === 0) {
+        return {
+          and: [{ expiryDate: null }, { [`id_${operator}`]: lastDomain.id }],
+        }
+      }
+      if (orderDirection === 'desc' && lastExpiryDate !== 0) {
+        return {
+          [`expiryDate_${operator}`]: `${lastExpiryDate}`,
+        }
+      }
+      return {
+        or: [
+          {
+            [`expiryDate_${operator}`]: `${lastExpiryDate}`,
+          },
+          { expiryDate: null },
+        ],
+      }
+    }
+    case 'name': {
+      return {
+        [`name_${operator}`]: lastDomain.name ?? '',
+      }
+    }
+    case 'labelName': {
+      return {
+        [`labelName_${operator}`]: lastDomain.labelName ?? '',
+      }
+    }
+    case 'createdAt': {
+      return {
+        [`createdAt_${operator}`]: `${lastDomain.createdAt.value / 1000}`,
+      }
+    }
+    default:
+      throw new InvalidOrderByError({
+        orderBy: orderBy || '<no orderBy provided>',
+        supportedOrderBys: ['expiryDate', 'name', 'labelName', 'createdAt'],
+      })
+  }
+}
+
+/**
+ * Gets the names for an address from the subgraph.
+ * @param client - {@link ClientWithEns}
+ * @param parameters - {@link GetNamesForAddressParameters}
+ * @returns Name array. {@link GetNamesForAddressReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getNamesForAddress } from '@ensdomains/ensjs/subgraph'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getNamesForAddress(client, { address: '0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7' })
+ */
+const getNamesForAddress = async (
+  client: ClientWithEns,
+  {
+    address,
+    filter: _filter,
+    orderBy = 'name',
+    orderDirection = 'asc',
+    pageSize = 100,
+    previousPage,
+  }: GetNamesForAddressParameters,
+): Promise<GetNamesForAddressReturnType> => {
+  const filter = {
+    owner: true,
+    registrant: true,
+    resolvedAddress: true,
+    wrappedOwner: true,
+    allowExpired: false,
+    allowDeleted: false,
+    allowReverseRecord: false,
+    ..._filter,
+  }
+
+  const subgraphClient = createSubgraphClient({ client })
+
+  const {
+    allowExpired,
+    allowDeleted,
+    allowReverseRecord,
+    searchString,
+    ...filters
+  } = filter
+  const ownerWhereFilters: DomainFilter[] = Object.entries(filters).reduce(
+    (prev, [key, value]) => {
+      if (value) {
+        if (!supportedOwnerFilters.includes(key as any))
+          throw new InvalidFilterKeyError({
+            filterKey: key,
+            supportedFilterKeys: supportedOwnerFilters,
+          })
+        return [
+          ...prev,
+          {
+            [key]: address.toLowerCase(),
+          },
+        ]
+      }
+      return prev
+    },
+    [] as DomainFilter[],
+  )
+
+  const hasFilterApplied = ownerWhereFilters.length > 0
+
+  if (!hasFilterApplied)
+    throw new FilterKeyRequiredError({
+      supportedFilterKeys: supportedOwnerFilters,
+      details: 'At least one ownership filter must be enabled',
+    })
+
+  const ownerWhereFilter: DomainFilter =
+    ownerWhereFilters.length > 1
+      ? { or: ownerWhereFilters }
+      : ownerWhereFilters[0]
+  const whereFilters: DomainFilter[] = [ownerWhereFilter]
+
+  if (previousPage?.length) {
+    whereFilters.push(
+      getOrderByFilter({
+        orderBy,
+        orderDirection,
+        previousPage,
+      }),
+    )
+  }
+
+  if (!allowReverseRecord) {
+    // Exclude domains with parent addr.reverse
+    // namehash of addr.reverse = 0x91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e2
+    whereFilters.push({
+      parent_not:
+        '0x91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e2',
+    })
+  }
+
+  if (!allowExpired) {
+    // Exclude domains that are expired
+    // if expiryDate is null, there is no expiry on the domain (registration or wrapped)
+    whereFilters.push({
+      or: [
+        { expiryDate_gt: `${Math.floor(Date.now() / 1000)}` },
+        { expiryDate: null },
+      ],
+    })
+  }
+
+  if (!allowDeleted) {
+    // exclude "deleted" domains
+    // when owner/resolver/registrant = null
+    whereFilters.push({
+      or: [
+        {
+          owner_not: EMPTY_ADDRESS,
+        },
+        {
+          resolver_not: null,
+        },
+        {
+          and: [
+            {
+              registrant_not: EMPTY_ADDRESS,
+            },
+            {
+              registrant_not: null,
+            },
+          ],
+        },
+      ],
+    })
+  }
+
+  if (searchString) {
+    // using labelName_contains instead of name_contains because name_contains
+    // includes the parent name
+    whereFilters.push({
+      labelName_contains: searchString,
+    })
+  }
+
+  const whereFilter: DomainFilter =
+    whereFilters.length > 1 ? { and: whereFilters } : whereFilters[0]
+
+  const query = gql`
+    query getNamesForAddress(
+      $orderBy: Domain_orderBy
+      $orderDirection: OrderDirection
+      $first: Int
+      $whereFilter: Domain_filter
+    ) {
+      domains(
+        orderBy: $orderBy
+        orderDirection: $orderDirection
+        first: $first
+        where: $whereFilter
+      ) {
+        ...DomainDetails
+        registration {
+          ...RegistrationDetails
+        }
+        wrappedDomain {
+          ...WrappedDomainDetails
+        }
+      }
+    }
+    ${domainDetailsFragment}
+    ${registrationDetailsFragment}
+    ${wrappedDomainDetailsFragment}
+  `
+
+  const result = await subgraphClient.request<
+    SubgraphResult,
+    {
+      orderBy: string
+      orderDirection: string
+      first: number
+      whereFilter: DomainFilter
+    }
+  >(query, {
+    orderBy,
+    orderDirection,
+    first: pageSize,
+    whereFilter,
+  })
+
+  if (!result) return []
+
+  const names = result.domains.map((domain) => {
+    const relation: GetNamesForAddressRelation = {}
+
+    if (domain.owner) {
+      relation.owner = domain.owner.id === address.toLowerCase()
+    }
+    if (domain.registrant) {
+      relation.registrant = domain.registrant.id === address.toLowerCase()
+    }
+    if (domain.wrappedOwner) {
+      relation.wrappedOwner = domain.wrappedOwner.id === address.toLowerCase()
+    }
+    if (domain.resolvedAddress) {
+      relation.resolvedAddress =
+        domain.resolvedAddress.id === address.toLowerCase()
+    }
+
+    return {
+      ...makeNameObject(domain),
+      relation,
+    }
+  })
+
+  return names
+}
+
+export default getNamesForAddress

package/src/functions/subgraph/getSubgraphRecords.ts

@@ -0,0 +1,183 @@
+import type { GraphQLClient } from 'graphql-request'
+import { gql } from 'graphql-request'
+import type { Address, Hex } from 'viem'
+import type { ClientWithEns } from '../../contracts/consts.js'
+import type { DateWithValue } from '../../types.js'
+import { namehash } from '../../utils/normalise.js'
+import { createSubgraphClient } from './client.js'
+
+export type GetSubgraphRecordsParameters = {
+  /** Name to get records for */
+  name: string
+  /** Resolver address to use */
+  resolverAddress?: Address
+}
+
+export type GetSubgraphRecordsReturnType = {
+  /** Name migration status from old ENS registry */
+  isMigrated: boolean
+  /** Initial name creation time */
+  createdAt: DateWithValue<number>
+  /** Array of text record keys */
+  texts: string[]
+  /** Array of coin ids */
+  coins: string[]
+} | null
+
+const inheritedResolverQuery = gql`
+  query getSubgraphRecords($id: String!) {
+    domain(id: $id) {
+      name
+      isMigrated
+      createdAt
+      resolver {
+        texts
+        coinTypes
+      }
+    }
+  }
+`
+
+const customResolverQuery = gql`
+  query getSubgraphRecords($id: String!, $resolverId: String!) {
+    domain(id: $id) {
+      name
+      isMigrated
+      createdAt
+    }
+    resolver(id: $resolverId) {
+      texts
+      coinTypes
+    }
+  }
+`
+
+type DomainResult = {
+  name: string
+  isMigrated: boolean
+  createdAt: string
+}
+
+type ResolverResult = {
+  texts: string[]
+  coinTypes: string[]
+}
+
+type InheritedResolverSubgraphResult = {
+  domain?: DomainResult & {
+    resolver?: ResolverResult
+  }
+}
+
+type CustomResolverSubgraphResult = {
+  domain?: DomainResult
+  resolver?: ResolverResult
+}
+
+type GetResolverResultReturnType = {
+  domain: DomainResult
+  resolver: ResolverResult | undefined
+} | null
+
+const getCustomResolverResult = async (
+  subgraphClient: GraphQLClient,
+  {
+    id,
+    resolverAddress,
+  }: {
+    id: Hex
+    resolverAddress: Address
+  },
+): Promise<GetResolverResultReturnType> => {
+  const resolverId = `${resolverAddress.toLowerCase()}-${id}`
+  const response = await subgraphClient.request<CustomResolverSubgraphResult>(
+    customResolverQuery,
+    {
+      id,
+      resolverId,
+    },
+  )
+  if (!response || !response.domain) return null
+  return {
+    domain: response.domain,
+    resolver: response.resolver,
+  }
+}
+
+const getInheritedResolverResult = async (
+  subgraphClient: GraphQLClient,
+  {
+    id,
+  }: {
+    id: Hex
+  },
+): Promise<GetResolverResultReturnType> => {
+  const response =
+    await subgraphClient.request<InheritedResolverSubgraphResult>(
+      inheritedResolverQuery,
+      {
+        id,
+      },
+    )
+  if (!response || !response.domain) return null
+  const { resolver, ...domain } = response.domain
+  return {
+    domain,
+    resolver,
+  }
+}
+
+/**
+ * Gets the records for a name from the subgraph
+ * @param client - {@link ClientWithEns}
+ * @param parameters - {@link GetSubgraphRecordsParameters}
+ * @returns Record object, or null if name was not found. {@link GetSubgraphRecordsReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getSubgraphRecords } from '@ensdomains/ensjs/subgraph'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getSubgraphRecords(client, { name: 'ens.eth' })
+ * // {
+ * //   isMigrated: true,
+ * //   createdAt: { date: 2019-08-26T05:09:01.000Z, value: 1566796141000 },
+ * //   texts: [ 'snapshot', 'url', 'avatar', 'com.twitter', 'com.github' ],
+ * //   coins: [ '60' ]
+ * // }
+ */
+const getSubgraphRecords = async (
+  client: ClientWithEns,
+  { name, resolverAddress }: GetSubgraphRecordsParameters,
+): Promise<GetSubgraphRecordsReturnType> => {
+  const subgraphClient = createSubgraphClient({ client })
+  const id = namehash(name)
+
+  const result = resolverAddress
+    ? await getCustomResolverResult(subgraphClient, { id, resolverAddress })
+    : await getInheritedResolverResult(subgraphClient, { id })
+  if (!result) return null
+  const { domain, resolver } = result
+
+  const { isMigrated, createdAt: stringCreatedAt } = domain
+  const intCreatedAt = parseInt(stringCreatedAt) * 1000
+  const texts = resolver?.texts || []
+  const coins = resolver?.coinTypes || []
+
+  return {
+    isMigrated,
+    createdAt: {
+      date: new Date(intCreatedAt),
+      value: intCreatedAt,
+    },
+    texts,
+    coins,
+  }
+}
+
+export default getSubgraphRecords

package/src/functions/subgraph/getSubgraphRegistrant.ts

@@ -0,0 +1,76 @@
+import { gql } from 'graphql-request'
+import { getAddress, labelhash, type Address } from 'viem'
+import type { ClientWithEns } from '../../contracts/consts.js'
+import { UnsupportedNameTypeError } from '../../errors/general.js'
+import { getNameType } from '../../utils/getNameType.js'
+import { createSubgraphClient } from './client.js'
+
+export type GetSubgraphRegistrantParameters = {
+  /** Name to get registrant for */
+  name: string
+}
+
+export type GetSubgraphRegistrantReturnType = Address | null
+
+const query = gql`
+  query getSubgraphRegistrant($id: String!) {
+    registration(id: $id) {
+      registrant {
+        id
+      }
+    }
+  }
+`
+
+type SubgraphResult = {
+  registration?: {
+    registrant: {
+      id: Address
+    }
+  }
+}
+
+/**
+ * Gets the name registrant from the subgraph.
+ * @param client - {@link ClientWithEns}
+ * @param parameters - {@link GetSubgraphRegistrantParameters}
+ * @returns Registrant address, or null if name was not found. {@link GetSubgraphRegistrantReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { addEnsContracts } from '@ensdomains/ensjs'
+ * import { getSubgraphRegistrant } from '@ensdomains/ensjs/subgraph'
+ *
+ * const client = createPublicClient({
+ *   chain: addEnsContracts(mainnet),
+ *   transport: http(),
+ * })
+ * const result = await getSubgraphRegistrant(client, { name: 'ens.eth' })
+ * // 0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9
+ */
+const getSubgraphRegistrant = async (
+  client: ClientWithEns,
+  { name }: GetSubgraphRegistrantParameters,
+): Promise<GetSubgraphRegistrantReturnType> => {
+  const labels = name.split('.')
+  const nameType = getNameType(name)
+  if (nameType !== 'eth-2ld')
+    throw new UnsupportedNameTypeError({
+      nameType,
+      supportedNameTypes: ['eth-2ld'],
+      details: 'Registrant can only be fetched for eth-2ld names',
+    })
+
+  const subgraphClient = createSubgraphClient({ client })
+
+  const result = await subgraphClient.request<SubgraphResult>(query, {
+    id: labelhash(labels[0]),
+  })
+
+  if (result?.registration?.registrant?.id)
+    return getAddress(result.registration.registrant.id)
+  return null
+}
+
+export default getSubgraphRegistrant