@x1id/resolve 0.10.0 → 0.12.0

package/dist/scoped.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Scoped customer-TLD names (`alices.testtld`) — the SDK last-mile of the
+ * namespace-registrar feature (#8484/#8485).
+ *
+ * A launched X1ID namespace `.tld` is a program-owned `Namespace` account at
+ * `["namespace", tld]` with `status == Active`. A name registered under it is a
+ * (always-tokenized) `Handle` at the TWO-SEED-plus-prefix PDA
+ * `["handle", tld, name]` — a DIFFERENT account from the bare `@name`'s
+ * `["handle", name]`, so `alices.testtld` and `@alices` can have different
+ * owners. This module is the shape classifier, the `Namespace` status reader and
+ * the injected PDA deriver the resolver uses to answer a scoped name; the
+ * owner/tokenization/verification read reuses the bare-handle authority path
+ * verbatim (see `createResolver` in index.ts).
+ *
+ * The resolution CONTRACT is `tools/api`'s `resolve_scoped` (Rust, the
+ * authority): canonicalize both halves exactly as the program does, confirm
+ * `.tld` is a launched Active namespace, then derive `["handle", tld, name]` and
+ * resolve its current authority — with `namespace` set to the TLD label.
+ *
+ * # Why the deriver is injected (not hand-rolled, not WASM)
+ *
+ * The WASM module exposes `["namespace", label]` (`deriveNamespaceAccount`) but
+ * NO two-seed scoped-handle derivation, and this package's one rule is to never
+ * hand-roll `find_program_address`'s ed25519 on-curve check in TypeScript (see
+ * wasm.ts). So `["handle", tld, name]` is derived through an INJECTED
+ * {@link ScopedHandleDeriver} — exactly the pattern the SNS adapter uses for its
+ * `.sol` name-account PDA. Build the default with {@link makeScopedHandleDeriver}
+ * (which uses `@solana/web3.js`), or inject your own (a test fake, or a runtime
+ * that already owns a `findProgramAddress`).
+ */
+/** Max byte length of a TLD label (`NAMESPACE_MAX_LEN`, the program's state.rs). */
+export declare const NAMESPACE_MAX_LEN = 16;
+/** A `name.tld` split, when `input` is SHAPED like a scoped customer-TLD name. */
+export interface ScopedCandidate {
+    /** The sub-name half (`"alices"`), lowercased; validated for real at resolve. */
+    readonly sub: string;
+    /** The TLD-label half (`"testtld"`), lowercased and label-charset-checked. */
+    readonly tld: string;
+}
+/**
+ * Classify `input` as a scoped customer-TLD candidate by SHAPE ONLY — no chain
+ * read. Returns the split, or null when the input is not that shape.
+ *
+ * The shape is a single interior dot with non-empty halves, no leading `@`, and
+ * a `tld` that is a plausible namespace label (the program's charset + the
+ * 1..=`NAMESPACE_MAX_LEN` length rule) and is NOT one of the reserved suffixes.
+ * Whether `.tld` is actually a launched namespace is a chain fact the resolver
+ * establishes separately — this only decides whether it is worth asking.
+ * Mirrors `app/src/lib/x1/namespaceRegister.ts`'s `namespaceSublabelShape` and
+ * the shape gate in `tools/api`'s `resolve`.
+ */
+export declare function scopedTldCandidate(input: string): ScopedCandidate | null;
+/**
+ * Whether a raw `Namespace` account's bytes say it is `Active`, byte-for-byte
+ * the authority's `namespace_active_from_bytes` (tools/api). Layout: disc(8) |
+ * label(Borsh `String`: u32 LE length + UTF-8 bytes) | status(u8), and
+ * `NamespaceStatus::Active` is the first enum variant (Borsh tag 0). Only the
+ * length prefix and the one status byte are parsed — nothing past it. `false`
+ * for any buffer too short to hold disc + length prefix + the status byte (a
+ * malformed/wrong account is never read as Active). The CALLER must also check
+ * the account is owned by the registry program — this reads bytes only.
+ */
+export declare function namespaceIsActive(data: Uint8Array): boolean;
+/**
+ * The one `find_program_address` derivation scoped resolution needs: the
+ * two-seed-plus-prefix scoped handle PDA `["handle", tld, name]`. Injected so
+ * the SDK core stays free of curve math (and of a hard `@solana/web3.js`
+ * dependency), and so tests can supply a deterministic fake.
+ */
+export interface ScopedHandleDeriver {
+    /** The `["handle", label, name]` PDA under `programId`, base58. */
+    scopedHandleKey(label: string, name: string, programId: string): Promise<string> | string;
+}
+/**
+ * Build the default scoped-handle deriver using `@solana/web3.js`.
+ *
+ * Seeds are `["handle", label, name]` under the registry program — exactly the
+ * order `tools/api`'s `scoped_handle_pda` and the program's
+ * `register_under_namespace` use, so the derived PDA is the account the name
+ * actually lives at. Prefers an INJECTED web3 module (robust under `file:` /
+ * `npm link`, where a bare specifier resolves from THIS package's realpath, not
+ * the consumer's); falls back to a dynamic import for a normal install.
+ */
+export declare function makeScopedHandleDeriver(web3Module?: unknown): Promise<ScopedHandleDeriver>;

package/dist/scoped.js

@@ -0,0 +1,126 @@
+/**
+ * Scoped customer-TLD names (`alices.testtld`) — the SDK last-mile of the
+ * namespace-registrar feature (#8484/#8485).
+ *
+ * A launched X1ID namespace `.tld` is a program-owned `Namespace` account at
+ * `["namespace", tld]` with `status == Active`. A name registered under it is a
+ * (always-tokenized) `Handle` at the TWO-SEED-plus-prefix PDA
+ * `["handle", tld, name]` — a DIFFERENT account from the bare `@name`'s
+ * `["handle", name]`, so `alices.testtld` and `@alices` can have different
+ * owners. This module is the shape classifier, the `Namespace` status reader and
+ * the injected PDA deriver the resolver uses to answer a scoped name; the
+ * owner/tokenization/verification read reuses the bare-handle authority path
+ * verbatim (see `createResolver` in index.ts).
+ *
+ * The resolution CONTRACT is `tools/api`'s `resolve_scoped` (Rust, the
+ * authority): canonicalize both halves exactly as the program does, confirm
+ * `.tld` is a launched Active namespace, then derive `["handle", tld, name]` and
+ * resolve its current authority — with `namespace` set to the TLD label.
+ *
+ * # Why the deriver is injected (not hand-rolled, not WASM)
+ *
+ * The WASM module exposes `["namespace", label]` (`deriveNamespaceAccount`) but
+ * NO two-seed scoped-handle derivation, and this package's one rule is to never
+ * hand-roll `find_program_address`'s ed25519 on-curve check in TypeScript (see
+ * wasm.ts). So `["handle", tld, name]` is derived through an INJECTED
+ * {@link ScopedHandleDeriver} — exactly the pattern the SNS adapter uses for its
+ * `.sol` name-account PDA. Build the default with {@link makeScopedHandleDeriver}
+ * (which uses `@solana/web3.js`), or inject your own (a test fake, or a runtime
+ * that already owns a `findProgramAddress`).
+ */
+import { ResolveError } from "./types.js";
+/** Max byte length of a TLD label (`NAMESPACE_MAX_LEN`, the program's state.rs). */
+export const NAMESPACE_MAX_LEN = 16;
+/** The suffixes that are NEVER a scoped X1ID TLD: the native X1NS namespaces
+ *  and the external ones the universal resolver owns. A scoped candidate whose
+ *  suffix is one of these is refused here so `.x1`/`.xnt`/`.xen` stay on the
+ *  X1NS path and `.sol`/`.eth` stay with their own adapters — the whole
+ *  never-conflate-a-namespace rule. */
+const RESERVED_SUFFIXES = new Set(["x1", "xnt", "xen", "sol", "eth"]);
+/**
+ * Classify `input` as a scoped customer-TLD candidate by SHAPE ONLY — no chain
+ * read. Returns the split, or null when the input is not that shape.
+ *
+ * The shape is a single interior dot with non-empty halves, no leading `@`, and
+ * a `tld` that is a plausible namespace label (the program's charset + the
+ * 1..=`NAMESPACE_MAX_LEN` length rule) and is NOT one of the reserved suffixes.
+ * Whether `.tld` is actually a launched namespace is a chain fact the resolver
+ * establishes separately — this only decides whether it is worth asking.
+ * Mirrors `app/src/lib/x1/namespaceRegister.ts`'s `namespaceSublabelShape` and
+ * the shape gate in `tools/api`'s `resolve`.
+ */
+export function scopedTldCandidate(input) {
+    const t = input.trim().toLowerCase();
+    if (!t || t.startsWith("@"))
+        return null;
+    const dot = t.lastIndexOf(".");
+    if (dot <= 0 || dot === t.length - 1)
+        return null;
+    const sub = t.slice(0, dot);
+    const tld = t.slice(dot + 1);
+    if (sub.includes("."))
+        return null; // a deeper dotted name is a true sub-subname
+    if (RESERVED_SUFFIXES.has(tld))
+        return null; // never conflate with X1NS / external
+    if (tld.length > NAMESPACE_MAX_LEN)
+        return null;
+    if (!/^[a-z0-9-]+$/.test(tld))
+        return null;
+    if (tld.startsWith("-") || tld.endsWith("-") || tld.includes("--") || /^[0-9]+$/.test(tld)) {
+        return null;
+    }
+    return { sub, tld };
+}
+/**
+ * Whether a raw `Namespace` account's bytes say it is `Active`, byte-for-byte
+ * the authority's `namespace_active_from_bytes` (tools/api). Layout: disc(8) |
+ * label(Borsh `String`: u32 LE length + UTF-8 bytes) | status(u8), and
+ * `NamespaceStatus::Active` is the first enum variant (Borsh tag 0). Only the
+ * length prefix and the one status byte are parsed — nothing past it. `false`
+ * for any buffer too short to hold disc + length prefix + the status byte (a
+ * malformed/wrong account is never read as Active). The CALLER must also check
+ * the account is owned by the registry program — this reads bytes only.
+ */
+export function namespaceIsActive(data) {
+    if (data.length < 12)
+        return false;
+    const labelLen = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(8, true);
+    const statusOff = 12 + labelLen;
+    if (data.length <= statusOff)
+        return false;
+    return data[statusOff] === 0;
+}
+/**
+ * Build the default scoped-handle deriver using `@solana/web3.js`.
+ *
+ * Seeds are `["handle", label, name]` under the registry program — exactly the
+ * order `tools/api`'s `scoped_handle_pda` and the program's
+ * `register_under_namespace` use, so the derived PDA is the account the name
+ * actually lives at. Prefers an INJECTED web3 module (robust under `file:` /
+ * `npm link`, where a bare specifier resolves from THIS package's realpath, not
+ * the consumer's); falls back to a dynamic import for a normal install.
+ */
+export async function makeScopedHandleDeriver(web3Module) {
+    let web3;
+    if (web3Module) {
+        web3 = web3Module;
+    }
+    else {
+        const spec = "@solana/web3.js";
+        try {
+            web3 = (await import(spec));
+        }
+        catch {
+            throw new ResolveError("not-configured", "scoped TLD resolution needs a deriver: install @solana/web3.js, pass the web3 module to makeScopedHandleDeriver, or inject `scopedHandleDeriver` in the resolver config");
+        }
+    }
+    const enc = new TextEncoder();
+    const handleSeed = enc.encode("handle");
+    return {
+        scopedHandleKey(label, name, programId) {
+            const program = new web3.PublicKey(programId);
+            const [key] = web3.PublicKey.findProgramAddressSync([handleSeed, enc.encode(label), enc.encode(name)], program);
+            return key.toBase58();
+        },
+    };
+}

package/dist/types.d.ts

@@ -1,8 +1,18 @@
-/** Which naming system produced a result. */
-export type Namespace = "handle" | "x1" | "xnt" | "xen";
+/**
+ * Which naming system produced a result.
+ *
+ * The first four are the fixed native namespaces. A SCOPED customer-TLD name
+ * (`alices.testtld`, #8484/#8485) carries its TLD LABEL here — an arbitrary,
+ * launch-time string — so the union is widened with `(string & {})`: literal
+ * autocomplete for the fixed four is preserved, while a scoped result can set
+ * `namespace` to its `.tld`. Compare against the literals as before; a value
+ * that is none of them is a scoped TLD label.
+ */
+export type Namespace = "handle" | "x1" | "xnt" | "xen" | (string & {});
 /**
  * Display label for a namespace. **Must be shown** next to any resolved
- * address — see the module docs on why this is not optional.
+ * address — see the module docs on why this is not optional. A scoped TLD label
+ * renders as `.<label>` (e.g. `.testtld`), the same as an X1NS suffix.
  */
 export declare function namespaceLabel(ns: Namespace): string;
 /** Confidence in the address a name resolves to. */
@@ -83,7 +93,16 @@ export interface Resolved {
 /** Chains a handle can carry a record for. SLIP-44 based. */
 export type Chain = "X1" | "SOL" | "ETH" | "BTC";
 export declare const CHAIN_COIN_TYPE: Readonly<Record<Chain, number>>;
-export type ResolveErrorCode = "unrecognized" | "ambiguous" | "invalid-handle" | "invalid-domain" | "not-found" | "no-record-for-chain" | "rpc-error";
+export type ResolveErrorCode = "unrecognized" | "ambiguous" | "invalid-handle" | "invalid-domain" | "not-found" | "no-record-for-chain" | "rpc-error"
+/**
+ * A reachable namespace exists for this name, but the adapter that would
+ * resolve it is not configured on this deployment (e.g. no `ETH_RPC_URL` for
+ * ENS, or no Solana mainnet RPC for SNS). Distinct from `unrecognized`: the
+ * name IS a known namespace — we just cannot reach its chain from here. A UI
+ * should surface "this namespace isn't enabled", not "unknown name", and the
+ * universal resolver NEVER fabricates an address to paper over it.
+ */
+ | "not-configured";
 /**
  * Finer-grained cause for a `ResolveError`, when the code alone is not
  * enough for a UI to explain what happened.

package/dist/types.js

@@ -1,6 +1,7 @@
 /**
  * Display label for a namespace. **Must be shown** next to any resolved
- * address — see the module docs on why this is not optional.
+ * address — see the module docs on why this is not optional. A scoped TLD label
+ * renders as `.<label>` (e.g. `.testtld`), the same as an X1NS suffix.
  */
 export function namespaceLabel(ns) {
     return ns === "handle" ? "@handle" : `.${ns}`;

package/dist/universal.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The X1ID Universal Resolver — one entry that resolves native `@handle` / X1NS
+ * names AND external namespaces (`.sol` via SNS, `.eth` via ENS) by reading each
+ * name's own chain, returning a single normalized {@link UniversalResolved}.
+ *
+ * ```ts
+ * import { createResolver, WasmResolver } from "@x1id/resolve";
+ * import { createUniversalResolver, makeSnsDeriver } from "@x1id/resolve";
+ *
+ * const wasm = await WasmResolver.fromBytes(wasmBytes);
+ * const native = createResolver({ rpcUrl: X1_RPC, wasm });
+ * const universal = createUniversalResolver({
+ *   native,
+ *   sns: { rpcUrl: SOLANA_RPC, deriver: await makeSnsDeriver() }, // live
+ *   ens: {},                                                      // gated off (no ETH_RPC_URL)
+ * });
+ *
+ * await universal.resolve("@jack");      // → source: "x1id"
+ * await universal.resolve("bob.sol");    // → source: "sns"
+ * await universal.resolve("bob.eth");    // → ResolveError "not-configured" (gated)
+ * ```
+ *
+ * Dispatch is by SHAPE (see universalDetect.ts) to exactly one adapter — never a
+ * try-one-then-fall-back chain. An unconfigured external namespace throws a typed
+ * `not-configured`; it does not poison resolution of the namespaces that ARE live.
+ */
+import type { Resolver } from "./index.js";
+import { type SnsAdapterConfig } from "./universalSns.js";
+import { type EnsAdapterConfig } from "./universalEns.js";
+import type { AdapterStatus, UniversalNamespace, UniversalResolveOptions, UniversalResolved } from "./universalTypes.js";
+export * from "./universalTypes.js";
+export { detectNamespace, isUniversalName, sourceForNamespace, externalLabel, type DetectedNamespace, } from "./universalDetect.js";
+export { createNativeAdapter } from "./universalNative.js";
+export { createSnsAdapter, makeSnsDeriver, snsHashedName, SPL_NAME_PROGRAM_ID, SOL_TLD_AUTHORITY, SNS_HASH_PREFIX, NAME_TOKENIZER_ID, SNS_MINT_PREFIX, type SnsAdapterConfig, type SnsDeriver, } from "./universalSns.js";
+export { createEnsAdapter, ensNamehash, ENS_REGISTRY_ADDRESS, type EnsAdapterConfig, type Keccak256, } from "./universalEns.js";
+export interface UniversalResolverConfig {
+    /** The native `@handle` / X1NS resolver (from `createResolver`). Required. */
+    readonly native: Resolver;
+    /** SNS (`.sol`) adapter config. Omit (or leave RPC/deriver unset) to gate it off. */
+    readonly sns?: SnsAdapterConfig;
+    /** ENS (`.eth`) adapter config. Omit (or leave ETH_RPC_URL unset) to gate it off. */
+    readonly ens?: EnsAdapterConfig;
+}
+export interface NamespaceResolver {
+    /**
+     * Resolve any supported name to a normalized result.
+     * @throws {ResolveError} with a `code` a UI can branch on — `unrecognized`,
+     *   `ambiguous`, `invalid-domain`, `not-found`, `rpc-error`, or
+     *   `not-configured` for a known-but-disabled namespace.
+     */
+    resolve(input: string, opts?: UniversalResolveOptions): Promise<UniversalResolved>;
+    /** Classify `input` into a namespace by shape, or null if unrecognized. */
+    detect(input: string): UniversalNamespace | null;
+    /** Per-source adapter status (which namespaces are live vs config-gated). */
+    status(): readonly AdapterStatus[];
+}
+/** Build the universal resolver over a native resolver plus optional external adapters. */
+export declare function createUniversalResolver(config: UniversalResolverConfig): NamespaceResolver;

package/dist/universal.js

@@ -0,0 +1,67 @@
+/**
+ * The X1ID Universal Resolver — one entry that resolves native `@handle` / X1NS
+ * names AND external namespaces (`.sol` via SNS, `.eth` via ENS) by reading each
+ * name's own chain, returning a single normalized {@link UniversalResolved}.
+ *
+ * ```ts
+ * import { createResolver, WasmResolver } from "@x1id/resolve";
+ * import { createUniversalResolver, makeSnsDeriver } from "@x1id/resolve";
+ *
+ * const wasm = await WasmResolver.fromBytes(wasmBytes);
+ * const native = createResolver({ rpcUrl: X1_RPC, wasm });
+ * const universal = createUniversalResolver({
+ *   native,
+ *   sns: { rpcUrl: SOLANA_RPC, deriver: await makeSnsDeriver() }, // live
+ *   ens: {},                                                      // gated off (no ETH_RPC_URL)
+ * });
+ *
+ * await universal.resolve("@jack");      // → source: "x1id"
+ * await universal.resolve("bob.sol");    // → source: "sns"
+ * await universal.resolve("bob.eth");    // → ResolveError "not-configured" (gated)
+ * ```
+ *
+ * Dispatch is by SHAPE (see universalDetect.ts) to exactly one adapter — never a
+ * try-one-then-fall-back chain. An unconfigured external namespace throws a typed
+ * `not-configured`; it does not poison resolution of the namespaces that ARE live.
+ */
+import { ResolveError } from "./types.js";
+import { detectNamespace, isUniversalName } from "./universalDetect.js";
+import { createNativeAdapter } from "./universalNative.js";
+import { createSnsAdapter } from "./universalSns.js";
+import { createEnsAdapter } from "./universalEns.js";
+export * from "./universalTypes.js";
+export { detectNamespace, isUniversalName, sourceForNamespace, externalLabel, } from "./universalDetect.js";
+export { createNativeAdapter } from "./universalNative.js";
+export { createSnsAdapter, makeSnsDeriver, snsHashedName, SPL_NAME_PROGRAM_ID, SOL_TLD_AUTHORITY, SNS_HASH_PREFIX, NAME_TOKENIZER_ID, SNS_MINT_PREFIX, } from "./universalSns.js";
+export { createEnsAdapter, ensNamehash, ENS_REGISTRY_ADDRESS, } from "./universalEns.js";
+/** Build the universal resolver over a native resolver plus optional external adapters. */
+export function createUniversalResolver(config) {
+    const nativeAdapter = createNativeAdapter(config.native);
+    const snsAdapter = createSnsAdapter(config.sns ?? {});
+    const ensAdapter = createEnsAdapter(config.ens ?? {});
+    const bySource = Object.freeze({
+        x1id: nativeAdapter,
+        sns: snsAdapter,
+        ens: ensAdapter,
+    });
+    return {
+        async resolve(input, opts) {
+            const { source } = detectNamespace(input); // throws unrecognized / ambiguous by shape
+            const adapter = bySource[source];
+            // Defensive: detection and dispatch agree by construction, but never let a
+            // mismatch silently resolve through the wrong chain.
+            if (!adapter) {
+                throw new ResolveError("unrecognized", `no adapter for "${input}"`, input);
+            }
+            return adapter.resolve(input, opts);
+        },
+        detect(input) {
+            if (!isUniversalName(input))
+                return null;
+            return detectNamespace(input).namespace;
+        },
+        status() {
+            return [nativeAdapter.status(), snsAdapter.status(), ensAdapter.status()];
+        },
+    };
+}

package/dist/universalDetect.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shape-based namespace detection for the universal resolver.
+ *
+ * Classification is by SHAPE ONLY — the same discipline as `parse.ts`'s
+ * `parseName`: we never try one namespace and fall back to another, because that
+ * is exactly how `@jack`, `jack.x1` and `jack.sol` get conflated and a transfer
+ * succeeds to the wrong person on the wrong chain.
+ */
+import type { NamespaceSource, UniversalNamespace } from "./universalTypes.js";
+export interface DetectedNamespace {
+    readonly namespace: UniversalNamespace;
+    readonly source: NamespaceSource;
+}
+/** The system that owns a given namespace. A scoped customer-TLD label (not one
+ *  of the fixed namespaces) is always the native X1ID system. */
+export declare function sourceForNamespace(ns: UniversalNamespace): NamespaceSource;
+/**
+ * Classify `input` into exactly one namespace by shape, or throw.
+ *
+ * - `@name`  → `handle` (never a dotted TLD; `@x.sol` is ambiguous → throws).
+ * - `name.<tld>` for a known tld → that namespace.
+ * - `name.<tld>` for an unknown tld shaped like a customer-TLD label → the
+ *   label itself, `source: "x1id"` (a SCOPED customer-TLD candidate, #8484/
+ *   #8485). Whether `.tld` is a LAUNCHED namespace is a chain fact the native
+ *   resolver establishes — this only classifies the shape.
+ * - anything else → `unrecognized`.
+ *
+ * @throws {ResolveError} `ambiguous` for `@…​.tld`; `unrecognized` otherwise.
+ */
+export declare function detectNamespace(input: string): DetectedNamespace;
+/** Non-throwing probe: is `input` shaped like any namespace the resolver knows? */
+export declare function isUniversalName(input: string): boolean;
+/**
+ * The single label of an external domain (`"bob"` from `"bob.sol"`), lowercased
+ * and validated. Shared by the SNS and ENS adapters so their label rules stay
+ * identical and homograph-safe.
+ *
+ * ASCII only — a payment identifier that renders a Cyrillic homograph as a
+ * successful result is a vector we refuse, the same stance as `parse.ts`.
+ * Interior dots (subdomains like `pay.bob.sol` / `pay.bob.eth`) use a different
+ * derivation per namespace and are NOT supported in this increment: rejected
+ * explicitly rather than mis-derived to a wrong account.
+ */
+export declare function externalLabel(input: string, suffix: UniversalNamespace): string;

package/dist/universalDetect.js

@@ -0,0 +1,105 @@
+/**
+ * Shape-based namespace detection for the universal resolver.
+ *
+ * Classification is by SHAPE ONLY — the same discipline as `parse.ts`'s
+ * `parseName`: we never try one namespace and fall back to another, because that
+ * is exactly how `@jack`, `jack.x1` and `jack.sol` get conflated and a transfer
+ * succeeds to the wrong person on the wrong chain.
+ */
+import { ResolveError } from "./types.js";
+import { scopedTldCandidate } from "./scoped.js";
+/** Suffix → namespace for the dotted (domain-shaped) FIXED namespaces. */
+const SUFFIX_NAMESPACE = Object.freeze({
+    x1: "x1",
+    xnt: "xnt",
+    xen: "xen",
+    sol: "sol",
+    eth: "eth",
+});
+const SOURCE_FOR = Object.freeze({
+    handle: "x1id",
+    x1: "x1id",
+    xnt: "x1id",
+    xen: "x1id",
+    sol: "sns",
+    eth: "ens",
+});
+/** The system that owns a given namespace. A scoped customer-TLD label (not one
+ *  of the fixed namespaces) is always the native X1ID system. */
+export function sourceForNamespace(ns) {
+    return SOURCE_FOR[ns] ?? "x1id";
+}
+/**
+ * Classify `input` into exactly one namespace by shape, or throw.
+ *
+ * - `@name`  → `handle` (never a dotted TLD; `@x.sol` is ambiguous → throws).
+ * - `name.<tld>` for a known tld → that namespace.
+ * - `name.<tld>` for an unknown tld shaped like a customer-TLD label → the
+ *   label itself, `source: "x1id"` (a SCOPED customer-TLD candidate, #8484/
+ *   #8485). Whether `.tld` is a LAUNCHED namespace is a chain fact the native
+ *   resolver establishes — this only classifies the shape.
+ * - anything else → `unrecognized`.
+ *
+ * @throws {ResolveError} `ambiguous` for `@…​.tld`; `unrecognized` otherwise.
+ */
+export function detectNamespace(input) {
+    const t = input.trim();
+    const looksHandle = t.startsWith("@");
+    const dot = t.lastIndexOf(".");
+    const suffix = dot === -1 ? "" : t.slice(dot + 1).toLowerCase();
+    const dottedNs = SUFFIX_NAMESPACE[suffix];
+    if (looksHandle && dottedNs) {
+        throw new ResolveError("ambiguous", `"${t}" is both a handle and a domain shape`, t);
+    }
+    if (looksHandle) {
+        return { namespace: "handle", source: "x1id" };
+    }
+    if (dottedNs) {
+        return { namespace: dottedNs, source: SOURCE_FOR[dottedNs] };
+    }
+    // A dotted, non-`@`, non-fixed-TLD name shaped like `name.<label>` is a scoped
+    // customer-TLD candidate — route it to the native (x1id) path, which reads
+    // the chain to confirm the TLD is launched (and otherwise re-throws
+    // `unrecognized`, so `.sol`/`.eth`/unknown TLDs are unaffected here).
+    const scoped = scopedTldCandidate(t);
+    if (scoped) {
+        return { namespace: scoped.tld, source: "x1id" };
+    }
+    throw new ResolveError("unrecognized", `"${t}" is not a handle or a known namespace (.x1 .xnt .xen .sol .eth)`, t);
+}
+/** Non-throwing probe: is `input` shaped like any namespace the resolver knows? */
+export function isUniversalName(input) {
+    try {
+        detectNamespace(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The single label of an external domain (`"bob"` from `"bob.sol"`), lowercased
+ * and validated. Shared by the SNS and ENS adapters so their label rules stay
+ * identical and homograph-safe.
+ *
+ * ASCII only — a payment identifier that renders a Cyrillic homograph as a
+ * successful result is a vector we refuse, the same stance as `parse.ts`.
+ * Interior dots (subdomains like `pay.bob.sol` / `pay.bob.eth`) use a different
+ * derivation per namespace and are NOT supported in this increment: rejected
+ * explicitly rather than mis-derived to a wrong account.
+ */
+export function externalLabel(input, suffix) {
+    const t = input.trim();
+    const dot = t.lastIndexOf(".");
+    if (dot <= 0 || t.slice(dot + 1).toLowerCase() !== suffix) {
+        throw new ResolveError("invalid-domain", `"${t}" is not a .${suffix} domain`, input);
+    }
+    const label = t.slice(0, dot).toLowerCase();
+    if (label.includes(".")) {
+        throw new ResolveError("invalid-domain", `subdomains are not supported yet (.${suffix}): "${t}"`, input);
+    }
+    if (!/^[a-z0-9-]+$/.test(label)) {
+        throw new ResolveError("invalid-domain", `.${suffix} labels must be ASCII letters, digits or hyphen`, input);
+    }
+    return label;
+}

package/dist/universalEns.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ENS adapter — `.eth` names on Ethereum. CONFIG-GATED.
+ *
+ * Full ENS resolution reads Ethereum mainnet: namehash(name) → the ENS registry's
+ * `resolver(node)` → that resolver's `addr(node)`. We do NOT have an Ethereum RPC
+ * endpoint configured on this deployment, so this adapter is GATED:
+ *
+ *   - Without `ethRpcUrl` (and a `keccak256` for namehash) it is NOT configured,
+ *     and `resolve` throws a typed `not-configured` ResolveError. It NEVER
+ *     fabricates an address — a gated namespace returns "not enabled", never a
+ *     guess.
+ *   - With both injected, it performs the real read over JSON-RPC `eth_call`.
+ *
+ * `keccak256` is injected for the same reason the native path injects curve math
+ * via WASM: this SDK does not hand-roll cryptographic primitives. A consumer with
+ * an Ethereum stack (ethers/viem/js-sha3) passes their vetted keccak256.
+ *
+ * The constants below are the well-known ENS MAINNET deployment values. This path
+ * has NOT been exercised against a live endpoint here (we have none) — enabling
+ * ENS is an owner decision (provision `ETH_RPC_URL`), at which point it must be
+ * verified end-to-end before being trusted.
+ */
+import type { NamespaceAdapter } from "./universalTypes.js";
+/** ENS registry (mainnet). `resolver(bytes32)` lives here. */
+export declare const ENS_REGISTRY_ADDRESS = "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
+/** A keccak-256 implementation over bytes → 32 bytes. Injected (not hand-rolled). */
+export type Keccak256 = (data: Uint8Array) => Uint8Array;
+export interface EnsAdapterConfig {
+    /** Ethereum mainnet JSON-RPC endpoint. Absent → adapter not configured. */
+    readonly ethRpcUrl?: string;
+    /** keccak-256 for namehash. Absent → adapter not configured. */
+    readonly keccak256?: Keccak256;
+    /** Optional fetch override (testing / custom transport). */
+    readonly fetchImpl?: typeof fetch;
+    /** ENS registry override (defaults to the mainnet registry). */
+    readonly registryAddress?: string;
+}
+/**
+ * EIP-137 namehash. `node("")` = 32 zero bytes; for each label (right-to-left)
+ * `node = keccak256(node ++ keccak256(label))`. Returns 32 bytes.
+ */
+export declare function ensNamehash(name: string, keccak256: Keccak256): Uint8Array;
+/** Build the `.eth` (ENS) adapter — gated on `ethRpcUrl` + `keccak256`. */
+export declare function createEnsAdapter(config?: EnsAdapterConfig): NamespaceAdapter;