@ensdomains/ensjs 4.1.1 → 5.0.0-alpha.0

package/src/actions/subgraph/getNamesForAddress.ts

@@ -0,0 +1,353 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { gql } from 'graphql-request'
+import type { Address } from 'viem'
+import type { ChainWithSubgraph } from '../../clients/chain.js'
+import {
+  FilterKeyRequiredError,
+  InvalidFilterKeyError,
+  InvalidOrderByError,
+} from '../../errors/subgraph.js'
+import { EMPTY_ADDRESS } from '../../utils/consts.js'
+import { createSubgraphClient } from './client.js'
+import {
+  type DomainFilter,
+  getCreatedAtOrderFilter,
+  getExpiryDateOrderFilter,
+} from './filters.js'
+import {
+  domainDetailsFragment,
+  registrationDetailsFragment,
+  type SubgraphDomain,
+  wrappedDomainDetailsFragment,
+} from './fragments.js'
+import { makeNameObject, type Name } from './utils.js'
+
+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 GetNamesForAddressReturnType = NameWithRelation[]
+
+export type GetNamesForAddressErrorType =
+  | InvalidOrderByError
+  | InvalidFilterKeyError
+  | FilterKeyRequiredError
+  | Error
+
+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 name */
+  searchString?: string
+  /** Search string filter type (default: `labelName`) */
+  searchType?: 'labelName' | 'name'
+  /** 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 NameWithRelation = Name & {
+  relation: GetNamesForAddressRelation
+}
+
+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': {
+      return getExpiryDateOrderFilter({
+        orderDirection,
+        lastDomain,
+      })
+    }
+    case 'name': {
+      return {
+        [`name_${operator}`]: lastDomain.name ?? '',
+      }
+    }
+    case 'labelName': {
+      return {
+        [`labelName_${operator}`]: lastDomain.labelName ?? '',
+      }
+    }
+    case 'createdAt': {
+      return getCreatedAtOrderFilter({ lastDomain, orderDirection })
+    }
+    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: { chain: ChainWithSubgraph },
+  {
+    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,
+    searchType: 'labelName',
+    ..._filter,
+  } as const
+
+  const subgraphClient = createSubgraphClient(client)
+
+  const {
+    allowExpired,
+    allowDeleted,
+    allowReverseRecord,
+    searchString,
+    searchType,
+    ...filters
+  } = filter
+
+  const ownerWhereFilters: DomainFilter[] = Object.entries(filters).reduce(
+    (prev, [key, value]) => {
+      if (value) {
+        if (!supportedOwnerFilters.includes(key as keyof typeof filters))
+          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) {
+    whereFilters.push({
+      [`${searchType}_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/actions/subgraph/getRecordHistory.ts

@@ -0,0 +1,126 @@
+import { gql } from 'graphql-request'
+import { namehash } from 'viem'
+import type { ChainWithSubgraph } from '../../clients/chain.js'
+import { createSubgraphClient } from './client.js'
+import type { ResolverEvent } from './events.js'
+import type { ReturnResolverEvent } from './getNameHistory.js'
+import { decodeResolverEvents } from './utils.js'
+
+type SubgraphResult = {
+  domain?: {
+    resolver?: {
+      events: ResolverEvent[]
+    }
+  }
+}
+
+export type GetRecordHistoryReturnType =
+  | ReturnResolverEvent[]
+  | null
+  | undefined
+
+export type RecordKey = 'name' | 'texts' | 'coins' | 'abi' | 'contentHash'
+
+export type GetRecordHistoryParameters<key extends RecordKey = RecordKey> = {
+  name: string
+  key: key
+}
+
+export type GetRecordHistoryErrorType = Error
+
+const events: Record<RecordKey, ResolverEvent['type'][]> = {
+  coins: ['AddrChanged', 'MulticoinAddrChanged'],
+  abi: ['AbiChanged'],
+  contentHash: ['ContenthashChanged'],
+  name: ['NameChanged'],
+  texts: ['TextChanged'],
+} as const
+
+export const getRecordHistory = async <key extends RecordKey = RecordKey>(
+  client: { chain: ChainWithSubgraph },
+  { name, key }: GetRecordHistoryParameters<key>,
+): Promise<GetRecordHistoryReturnType> => {
+  const subgraphClient = createSubgraphClient(client)
+
+  const query = gql`
+    query getRecordHistory($id: String!) {
+      domain(id: $id) {
+        resolver {
+          events {
+            id
+            blockNumber
+            transactionID
+            type: __typename
+            ${
+              key === 'name'
+                ? `
+            ... on NameChanged {
+              name
+            }
+            `
+                : ''
+            }
+            ${
+              key === 'texts'
+                ? `
+            ... on TextChanged {
+              key
+              value
+            }
+            `
+                : ''
+            }
+            ${
+              key === 'coins'
+                ? `
+            ... on MulticoinAddrChanged {
+              coinType
+              multiaddr: addr
+            }
+            ... on AddrChanged {
+              addr {
+                id
+              }
+            }
+            `
+                : ''
+            }
+            ${
+              key === 'abi'
+                ? `
+            ... on AbiChanged {
+              contentType
+            }
+            `
+                : ''
+            }
+            ${
+              key === 'contentHash'
+                ? `
+            ... on ContenthashChanged {
+              hash
+            }
+            `
+                : ''
+            }
+          }
+        }
+      }
+    }
+  `
+
+  const queryVars = {
+    id: namehash(name),
+  }
+
+  const result = await subgraphClient.request<SubgraphResult, typeof queryVars>(
+    query,
+    queryVars,
+  )
+
+  return decodeResolverEvents(
+    (result.domain?.resolver?.events || []).filter((el) =>
+      events[key].includes(el.type),
+    ),
+  )
+}

package/src/actions/subgraph/getResolvedNamesForAddress.ts

@@ -0,0 +1,60 @@
+import type { Address, Hex } from 'viem'
+import type { ChainWithSubgraph } from '../../clients/chain.js'
+import { createSubgraphClient } from './client.js'
+
+type SubgraphResult = {
+  domains: {
+    name: string
+    resolver: {
+      coinTypes: string[]
+    }
+  }[]
+}
+
+export type GetResolvedNamesForAddressParameters = {
+  address: Address
+}
+
+export type GetResolvedNamesForAddressReturnType = {
+  name: string
+  coinTypes: string[]
+}[]
+
+export type GetResolvedNamesForAddressErrorType = Error
+
+/**
+ * Gets domains from the subgraph that resolve to a given address.
+ * @param client - {@link ClientWithEns}
+ * @param parameters - {@link GetNamesResolvedToAddressParameters}
+ * @returns Name array. {@link GetNamesResolvedToAddressReturnType}
+ *
+ * @example
+ * const result = await getResolvedNamesForAddress(client, { address: '0xD3B282e9880cDcB1142830731cD83f7ac0e1043f' })
+ */
+export const getResolvedNamesForAddress = async (
+  client: { chain: ChainWithSubgraph },
+  { address }: GetResolvedNamesForAddressParameters,
+) => {
+  const subgraphClient = createSubgraphClient(client)
+
+  const query = `
+    query ($address: String!) {
+      domains(where: { resolvedAddress: $address }) {
+        name
+        resolver {
+          coinTypes
+        }
+      }
+    }
+  `
+
+  const result = await subgraphClient.request<
+    SubgraphResult,
+    GetResolvedNamesForAddressParameters
+  >(query, { address: address.toLowerCase() as Hex })
+
+  return result.domains.map((domain) => ({
+    name: domain.name,
+    coinTypes: domain.resolver?.coinTypes ?? [],
+  }))
+}

package/src/actions/subgraph/getSubgraphRecords.ts

@@ -0,0 +1,185 @@
+import type { GraphQLClient } from 'graphql-request'
+import { gql } from 'graphql-request'
+import type { Address, Hex } from 'viem'
+import { namehash } from 'viem/ens'
+import type { ChainWithSubgraph } from '../../clients/chain.js'
+import type { DateWithValue } from '../../types/index.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
+
+export type GetSubgraphRecordsErrorType = Error
+
+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: { chain: ChainWithSubgraph },
+  { 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 = Number.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