enssdk 1.15.1 → 1.16.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 NameHash
+Copyright (c) 2026 NameHash Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -10,10 +10,10 @@ Learn more about [ENSNode](https://ensnode.io/) from [the ENSNode docs](https://
 npm install enssdk
 ```
 
-> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.13. If you are querying them from your own app, you **must** use `enssdk@1.13.1`. The latest published version (`1.14.0+`) contains breaking changes in the Omnigraph API data model not yet deployed to our hosted infrastructure. This notice will be removed once the hosted instances are upgraded.
+> **Version compatibility:** Our hosted ENSNode instances currently run ENSNode v1.15. If you are querying them from your own app, pin `enssdk` to the matching version — the Omnigraph API data model can change between versions.
 >
 > ```bash
-> npm install enssdk@1.13.1
+> npm install enssdk@1.15.2
 > ```
 
 ## Usage
@@ -32,14 +32,19 @@ const client = createEnsNodeClient({ url: "https://api.alpha.ensnode.io" });
 import { createEnsNodeClient } from "enssdk/core";
 import { omnigraph, graphql } from "enssdk/omnigraph";
 
-const client = createEnsNodeClient({ url: "https://api.alpha.ensnode.io" })
-  .extend(omnigraph);
+const client = createEnsNodeClient({ url: "https://api.alpha.ensnode.io" }).extend(omnigraph);
 
 const MyQuery = graphql(`
   query MyQuery($name: Name!) {
     domain(by: { name: $name }) {
-      canonical { name { interpreted } }
-      registration { expiry }
+      canonical {
+        name {
+          interpreted
+        }
+      }
+      registration {
+        expiry
+      }
     }
   }
 `);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as Hex, A as Address, N as NormalizedAddress, I as InterpretedLabel, B as BeautifiedLabel, a as InterpretedName, b as BeautifiedName, c as AccountId, d as AssetId, C as ChainId, e as Node, D as DNSEncodedLiteralName, L as LiteralLabel, f as DNSEncodedName, E as ENSv1RegistryId, g as ENSv2RegistryId, h as ENSv1DomainId, i as ENSv1VirtualRegistryId, S as StorageId, j as ENSv2DomainId, P as PermissionsId, k as PermissionsResourceId, l as PermissionsUserId, m as DomainId, R as RegistrationId, n as RenewalId, o as ResolverId, p as ResolverRecordsId, T as TokenId, q as LabelHash, r as Label, s as Name, t as LiteralName, u as LabelHashPath, v as EncodedLabelHash } from './evm-Dd4Y60SN.js';
-export { w as AssetNamespace, x as AssetNamespaces, y as CanonicalPath, z as DNSEncodedPartiallyInterpretedName, F as DefaultableChainId, G as DurationBigInt, J as RegistryId, K as SubgraphInterpretedLabel, M as SubgraphInterpretedName, U as UnixTimestampBigInt, W as Wei } from './evm-Dd4Y60SN.js';
+import { A as Address, N as NormalizedAddress, I as InterpretedLabel, B as BeautifiedLabel, a as InterpretedName, b as BeautifiedName, c as AccountId, d as AccountIdString, e as AssetId, f as AssetIdString, C as ChainId, g as Node, D as DNSEncodedLiteralName, L as LiteralLabel, h as DNSEncodedName, i as Name, E as ENSv1RegistryId, j as ENSv2RegistryId, k as ENSv1DomainId, l as ENSv1VirtualRegistryId, S as StorageId, m as ENSv2DomainId, P as PermissionsId, n as PermissionsResourceId, o as PermissionsUserId, p as DomainId, R as RegistrationId, q as RenewalId, r as ResolverId, s as ResolverRecordsId, T as TokenId, t as LabelHash, u as RegistryId, U as UnindexedDomainId, v as InterfaceId, w as Label, x as LiteralName, y as LabelHashPath, z as EncodedLabelHash } from './shared-CZeZrvuq.js';
+export { F as AssetNamespace, G as AssetNamespaces, H as BinanceAddress, J as BitcoinAddress, K as BitcoinCashAddress, M as CanonicalPath, O as ChainIdString, Q as ContentType, V as DNSEncodedPartiallyInterpretedName, W as DatetimeISO8601, X as DefaultableChainId, Y as DogecoinAddress, Z as Duration, _ as DurationBigInt, $ as Email, a0 as Hex, a1 as JsonValue, a2 as LitecoinAddress, a3 as MonacoinAddress, a4 as RecordVersion, a5 as RippleAddress, a6 as RootstockAddress, a7 as SolanaAddress, a8 as SubgraphInterpretedLabel, a9 as SubgraphInterpretedName, aa as UnixTimestamp, ab as UnixTimestampBigInt, ac as UrlString, ad as Wei } from './shared-CZeZrvuq.js';
 import { EvmCoinType, CoinType } from '@ensdomains/address-encoder';
 export { CoinType, EvmCoinType } from '@ensdomains/address-encoder';
 import 'viem';
@@ -17,83 +17,6 @@ type EACResource = bigint;
  */
 type EACRoleBitmap = bigint;
 
-/**
- * ABI content type per ENSIP-4.
- *
- * Single-bit values (1=JSON, 2=zlib-JSON, 4=CBOR, 8=URI) identify a stored ABI encoding.
- * `setABI` requires a power-of-2 value.
- *
- * Bitmask unions of those bits are used when reading via `ABI(node, contentTypes)`; the
- * resolver returns the first stored ABI whose bit is present in the mask (lowest bit first).
- *
- * @see https://github.com/ensdomains/ens-contracts/blob/91c966febd7b55494269df830fc6775f040b927b/contracts/resolvers/profiles/ABIResolver.sol
- */
-type ContentType = bigint;
-/**
- * ERC-165 4-byte interface selector.
- *
- * @see https://github.com/ensdomains/ens-contracts/blob/91c966febd7b55494269df830fc6775f040b927b/contracts/resolvers/profiles/InterfaceResolver.sol
- */
-type InterfaceId = Hex;
-/**
- * IVersionableResolver record version. Bumped by `VersionChanged`, which invalidates all prior
- * records for the node.
- *
- * @see https://github.com/ensdomains/ens-contracts/blob/91c966febd7b55494269df830fc6775f040b927b/contracts/resolvers/profiles/IVersionableResolver.sol
- */
-type RecordVersion = bigint;
-
-/**
- * Unix timestamp value
- *
- * Represents the number of seconds that have elapsed
- * since January 1, 1970 (midnight UTC/GMT).
- *
- * Guaranteed to be an integer. May be zero or negative to represent a time at or
- * before Jan 1, 1970.
- */
-type UnixTimestamp = number;
-/**
- * Duration
- *
- * Representing a duration in seconds.
- *
- * Guaranteed to be a non-negative integer.
- */
-type Duration = number;
-/**
- * Serialized representation of {@link ChainId}.
- **/
-type ChainIdString = string;
-/**
- * Datetime value following the ISO 8601 standard.
- *
- * @see https://www.iso.org/iso-8601-date-and-time-format.html
- */
-type DatetimeISO8601 = string;
-/**
- * Serialized representation of a {@link URL}.
- */
-type UrlString = string;
-/**
- * String representation of {@link AccountId}.
- *
- * Formatted as a fully lowercase CAIP-10 AccountId.
- *
- * @see https://chainagnostic.org/CAIPs/caip-10
- */
-type AccountIdString = string;
-/**
- * String representation of {@link AssetId}.
- *
- * Formatted as a fully lowercase CAIP-19 AssetId.
- *
- * @see https://chainagnostic.org/CAIPs/caip-19
- * @example "eip155:1/erc721:0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85/0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc"
- *          for vitalik.eth in the eth base registrar on mainnet.
- */
-type AssetIdString = string;
-
 /**
  * Determines whether an {@link Address} is a {@link NormalizedAddress}.
  */
@@ -258,6 +181,18 @@ declare function decodeDNSEncodedLiteralName(packet: DNSEncodedLiteralName): Lit
  */
 declare function decodeDNSEncodedName(packet: DNSEncodedName): string[];
 
+/** ENS text record types supported by the ENS Metadata Service image endpoints. */
+type EnsMetadataImageRecord = "avatar" | "header";
+/**
+ * Build an HTTP-compatible image URL for a name on the given ENS namespace that (once fetched)
+ * loads the requested profile image record from the ENS Metadata Service
+ * (https://metadata.ens.domains/docs).
+ *
+ * The returned URL is dynamically built based on the provided ENS namespace. Not all ENS
+ * namespaces are supported by the ENS Metadata Service. Therefore, the returned URL may be null.
+ */
+declare function getEnsMetadataServiceImageUrl(name: Name, namespaceId: string, record: EnsMetadataImageRecord): URL | null;
+
 declare const makeENSv1RegistryId: (accountId: AccountId) => ENSv1RegistryId;
 declare const makeENSv2RegistryId: (accountId: AccountId) => ENSv2RegistryId;
 declare const makeENSv1VirtualRegistryId: (accountId: AccountId, node: Node) => ENSv1VirtualRegistryId;
@@ -270,6 +205,15 @@ declare const makeConcreteRegistryId: (accountId: AccountId) => ENSv1RegistryId
 declare const makeResolverId: (contract: AccountId) => ResolverId;
 declare const makeENSv1DomainId: (accountId: AccountId, node: Node) => ENSv1DomainId;
 declare const makeENSv2DomainId: (registry: AccountId, storageId: StorageId) => ENSv2DomainId;
+/**
+ * Stringifies the id of a resolvable-but-unindexed Domain from the {@link RegistryId} of the
+ * Registry that manages the ancestor Domain bearing the wildcard Resolver, and the `node` (namehash)
+ * of the unindexed name. See {@link UnindexedDomainId}.
+ *
+ * @dev Prefixed with `unindexed-` to unambiguously disambiguate from an {@link ENSv1DomainId}, which
+ * shares the same `${registryId}-${node}` tail shape.
+ */
+declare const makeUnindexedDomainId: (registryId: RegistryId, node: Node) => UnindexedDomainId;
 /**
  * Computes a Label's {@link StorageId} given its TokenId or LabelHash.
  */
@@ -662,6 +606,31 @@ declare function reinterpretLabel(label: InterpretedLabel): InterpretedLabel;
  */
 declare function reinterpretName(name: InterpretedName): InterpretedName;
 
+/**
+ * A {@link ResolvableName} is an {@link InterpretedName} that can actually be resolved via the ENS
+ * protocol — i.e. it can be DNS-encoded and passed to a Resolver. It requires that every label:
+ * - is normalized,
+ * - is a known literal label (NOT an Encoded LabelHash — an unknown label cannot be DNS-encoded), and
+ * - DNS-encodes to fewer than {@link MAX_RESOLVABLE_LABEL_BYTE_LENGTH} bytes.
+ *
+ * @dev technically names with unnormalized labels are resolvable by the UniversalResolver (which
+ * does not check normalization), but to reduce edge cases and avoid footguns, we intentionally
+ * include this additional constraint. This also enforces that a ResolvableName within ENSNode is
+ * a strict subset of InterpretedName and InterpretedName-based operations (like {@link namehashInterpretedName})
+ * function identically on ResolvableNames.
+ */
+type ResolvableName = InterpretedName & {
+    __brand: "ResolvableName";
+};
+/**
+ * Determines whether `name` is a {@link ResolvableName}.
+ */
+declare function isResolvableName(name: InterpretedName): name is ResolvableName;
+/**
+ * Asserts that `name` is a {@link ResolvableName}, returning it, or throws.
+ */
+declare function asResolvableName(name: InterpretedName): ResolvableName;
+
 /**
  * Gets the Label used for the reverse names of subnames as per ENSIP-11 & ENSIP-19.
  *
@@ -693,4 +662,4 @@ declare const coinTypeReverseLabel: (coinType: CoinType) => LiteralLabel;
  */
 declare function reverseName(address: NormalizedAddress, coinType: CoinType): LiteralName;
 
-export { ADDR_REVERSE_NODE, AccountId, type AccountIdString, Address, AssetId, type AssetIdString, BeautifiedLabel, BeautifiedName, ChainId, type ChainIdString, type ContentType, DEFAULT_EVM_CHAIN_ID, DEFAULT_EVM_COIN_TYPE, DNSEncodedLiteralName, DNSEncodedName, type DatetimeISO8601, DomainId, type Duration, type EACResource, type EACRoleBitmap, ENS_ROOT_NAME, ENS_ROOT_NODE, ENSv1DomainId, ENSv1RegistryId, ENSv1VirtualRegistryId, ENSv2DomainId, ENSv2RegistryId, ETH_COIN_TYPE, ETH_NODE, EncodedLabelHash, Hex, type InterfaceId, InterpretedLabel, InterpretedName, Label, LabelHash, LabelHashPath, LiteralLabel, LiteralName, Name, Node, NormalizedAddress, PermissionsId, PermissionsResourceId, PermissionsUserId, ROOT_RESOURCE, type RecordVersion, RegistrationId, RenewalId, ResolverId, ResolverRecordsId, StorageId, TokenId, type UnixTimestamp, type UrlString, addrReverseLabel, asInterpretedLabel, asInterpretedName, asLiteralLabel, asLiteralName, asNormalizedAddress, beautifyInterpretedLabel, beautifyInterpretedName, beautifyName, bigintToCoinType, coinTypeReverseLabel, coinTypeToEvmChainId, constructSubInterpretedName, decodeDNSEncodedLiteralName, decodeDNSEncodedName, decodeEncodedLabelHash, encodeLabelHash, ensureInterpretedLabel, evmChainIdToCoinType, getNameHierarchy, getParentInterpretedName, interpretTokenIdAsLabelHash, interpretTokenIdAsNode, interpretedLabelsToInterpretedName, interpretedLabelsToLabelHashPath, interpretedNameToInterpretedLabels, isEncodedLabelHash, isInterfaceId, isInterpretedLabel, isInterpretedName, isLabelHash, isNormalizedAddress, isNormalizedLabel, isNormalizedName, labelhashInterpretedLabel, labelhashLiteralLabel, literalLabelToInterpretedLabel, literalLabelsToInterpretedName, literalLabelsToLiteralName, literalNameToInterpretedName, literalNameToLiteralLabels, makeConcreteRegistryId, makeENSv1DomainId, makeENSv1RegistryId, makeENSv1VirtualRegistryId, makeENSv2DomainId, makeENSv2RegistryId, makePermissionsId, makePermissionsResourceId, makePermissionsUserId, makeRegistrationId, makeRenewalId, makeResolverId, makeResolverRecordsId, makeStorageId, makeSubdomainNode, namehashInterpretedName, normalizeLabel, normalizeName, parseEncodedLabelHash, parseLabelHash, parseLabelHashOrEncodedLabelHash, parseReverseName, reinterpretLabel, reinterpretName, reverseName, stringifyAccountId, stringifyAssetId, toNormalizedAddress };
+export { ADDR_REVERSE_NODE, AccountId, AccountIdString, Address, AssetId, AssetIdString, BeautifiedLabel, BeautifiedName, ChainId, DEFAULT_EVM_CHAIN_ID, DEFAULT_EVM_COIN_TYPE, DNSEncodedLiteralName, DNSEncodedName, DomainId, type EACResource, type EACRoleBitmap, ENS_ROOT_NAME, ENS_ROOT_NODE, ENSv1DomainId, ENSv1RegistryId, ENSv1VirtualRegistryId, ENSv2DomainId, ENSv2RegistryId, ETH_COIN_TYPE, ETH_NODE, EncodedLabelHash, type EnsMetadataImageRecord, InterfaceId, InterpretedLabel, InterpretedName, Label, LabelHash, LabelHashPath, LiteralLabel, LiteralName, Name, Node, NormalizedAddress, PermissionsId, PermissionsResourceId, PermissionsUserId, ROOT_RESOURCE, RegistrationId, RegistryId, RenewalId, type ResolvableName, ResolverId, ResolverRecordsId, StorageId, TokenId, UnindexedDomainId, addrReverseLabel, asInterpretedLabel, asInterpretedName, asLiteralLabel, asLiteralName, asNormalizedAddress, asResolvableName, beautifyInterpretedLabel, beautifyInterpretedName, beautifyName, bigintToCoinType, coinTypeReverseLabel, coinTypeToEvmChainId, constructSubInterpretedName, decodeDNSEncodedLiteralName, decodeDNSEncodedName, decodeEncodedLabelHash, encodeLabelHash, ensureInterpretedLabel, evmChainIdToCoinType, getEnsMetadataServiceImageUrl, getNameHierarchy, getParentInterpretedName, interpretTokenIdAsLabelHash, interpretTokenIdAsNode, interpretedLabelsToInterpretedName, interpretedLabelsToLabelHashPath, interpretedNameToInterpretedLabels, isEncodedLabelHash, isInterfaceId, isInterpretedLabel, isInterpretedName, isLabelHash, isNormalizedAddress, isNormalizedLabel, isNormalizedName, isResolvableName, labelhashInterpretedLabel, labelhashLiteralLabel, literalLabelToInterpretedLabel, literalLabelsToInterpretedName, literalLabelsToLiteralName, literalNameToInterpretedName, literalNameToLiteralLabels, makeConcreteRegistryId, makeENSv1DomainId, makeENSv1RegistryId, makeENSv1VirtualRegistryId, makeENSv2DomainId, makeENSv2RegistryId, makePermissionsId, makePermissionsResourceId, makePermissionsUserId, makeRegistrationId, makeRenewalId, makeResolverId, makeResolverRecordsId, makeStorageId, makeSubdomainNode, makeUnindexedDomainId, namehashInterpretedName, normalizeLabel, normalizeName, parseEncodedLabelHash, parseLabelHash, parseLabelHashOrEncodedLabelHash, parseReverseName, reinterpretLabel, reinterpretName, reverseName, stringifyAccountId, stringifyAssetId, toNormalizedAddress };

package/dist/index.js

@@ -278,6 +278,29 @@ function decodeDNSEncodedName(packet) {
   return segments;
 }
 
+// src/lib/ens-metadata-service.ts
+var METADATA_NETWORKS = {
+  mainnet: "mainnet",
+  sepolia: "sepolia"
+};
+var URI_SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+function namespaceIdToMetadataNetwork(namespaceId) {
+  switch (namespaceId) {
+    case "mainnet":
+      return METADATA_NETWORKS.mainnet;
+    case "sepolia":
+      return METADATA_NETWORKS.sepolia;
+    default:
+      return null;
+  }
+}
+function getEnsMetadataServiceImageUrl(name, namespaceId, record) {
+  if (name.startsWith("//") || URI_SCHEME_PATTERN.test(name)) return null;
+  const network = namespaceIdToMetadataNetwork(namespaceId);
+  if (!network) return null;
+  return new URL(name, `https://metadata.ens.domains/${network}/${record}/`);
+}
+
 // src/lib/ids.ts
 import { hexToBigInt } from "viem";
 
@@ -293,6 +316,7 @@ var makeConcreteRegistryId = (accountId) => _stringifyAccountId(accountId);
 var makeResolverId = (contract) => _stringifyAccountId(contract);
 var makeENSv1DomainId = (accountId, node) => [_stringifyAccountId(accountId), node].join("-");
 var makeENSv2DomainId = (registry, storageId) => [_stringifyAccountId(registry), storageId.toString()].join("-");
+var makeUnindexedDomainId = (registryId, node) => ["unindexed", registryId, node].join("-");
 var makeStorageId = (tokenIdOrLabelHash) => {
   const tokenId = typeof tokenIdOrLabelHash === "bigint" ? tokenIdOrLabelHash : hexToBigInt(tokenIdOrLabelHash);
   return zeroLower32Bits(tokenId);
@@ -415,6 +439,21 @@ function reinterpretName(name) {
   return interpretedLabelsToInterpretedName(labels.map(reinterpretLabel));
 }
 
+// src/lib/resolvable-name.ts
+import { stringToBytes as stringToBytes2 } from "viem";
+var MAX_RESOLVABLE_LABEL_BYTE_LENGTH = 256;
+function isResolvableName(name) {
+  for (const label of interpretedNameToInterpretedLabels(name)) {
+    if (isEncodedLabelHash(label)) return false;
+    if (stringToBytes2(label).length >= MAX_RESOLVABLE_LABEL_BYTE_LENGTH) return false;
+  }
+  return true;
+}
+function asResolvableName(name) {
+  if (isResolvableName(name)) return name;
+  throw new Error(`Not a valid ResolvableName: '${name}'`);
+}
+
 // src/lib/reverse-name.ts
 var ADDR_LABEL = asLiteralLabel("addr");
 var DEFAULT_LABEL = asLiteralLabel("default");
@@ -457,6 +496,7 @@ export {
   asLiteralLabel,
   asLiteralName,
   asNormalizedAddress,
+  asResolvableName,
   beautifyInterpretedLabel,
   beautifyInterpretedName,
   beautifyName,
@@ -470,6 +510,7 @@ export {
   encodeLabelHash,
   ensureInterpretedLabel,
   evmChainIdToCoinType,
+  getEnsMetadataServiceImageUrl,
   getNameHierarchy,
   getParentInterpretedName,
   interpretTokenIdAsLabelHash,
@@ -485,6 +526,7 @@ export {
   isNormalizedAddress,
   isNormalizedLabel,
   isNormalizedName,
+  isResolvableName,
   labelhashInterpretedLabel,
   labelhashLiteralLabel,
   literalLabelToInterpretedLabel,
@@ -507,6 +549,7 @@ export {
   makeResolverRecordsId,
   makeStorageId,
   makeSubdomainNode,
+  makeUnindexedDomainId,
   namehashInterpretedName,
   normalizeLabel,
   normalizeName,