@x1id/resolve 0.11.0 → 0.12.0

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;

package/dist/universalEns.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { ResolveError } from "./types.js";
+import { externalLabel } from "./universalDetect.js";
+/** ENS registry (mainnet). `resolver(bytes32)` lives here. */
+export const ENS_REGISTRY_ADDRESS = "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
+/** `resolver(bytes32)` selector = keccak256("resolver(bytes32)")[:4]. */
+const SELECTOR_RESOLVER = "0178b8bf";
+/** `addr(bytes32)` selector = keccak256("addr(bytes32)")[:4]. */
+const SELECTOR_ADDR = "3b3b57de";
+const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+function toHex(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}
+/**
+ * EIP-137 namehash. `node("")` = 32 zero bytes; for each label (right-to-left)
+ * `node = keccak256(node ++ keccak256(label))`. Returns 32 bytes.
+ */
+export function ensNamehash(name, keccak256) {
+    let node = new Uint8Array(32);
+    if (name.length > 0) {
+        const labels = name.split(".");
+        const enc = new TextEncoder();
+        for (let i = labels.length - 1; i >= 0; i--) {
+            const labelHash = keccak256(enc.encode(labels[i]));
+            const joined = new Uint8Array(64);
+            joined.set(node, 0);
+            joined.set(labelHash, 32);
+            node = keccak256(joined);
+        }
+    }
+    return node;
+}
+/** The 20-byte address in the last 20 bytes of a 32-byte ABI word, as 0x-hex. */
+function addressFromWord(hexWord) {
+    const clean = hexWord.startsWith("0x") ? hexWord.slice(2) : hexWord;
+    if (clean.length < 64)
+        return null;
+    const addr = "0x" + clean.slice(24, 64).toLowerCase();
+    return addr === ZERO_ADDRESS ? null : addr;
+}
+/** Build the `.eth` (ENS) adapter — gated on `ethRpcUrl` + `keccak256`. */
+export function createEnsAdapter(config = {}) {
+    const registry = config.registryAddress ?? ENS_REGISTRY_ADDRESS;
+    const configured = Boolean(config.ethRpcUrl && config.keccak256);
+    function status() {
+        if (configured)
+            return { namespace: "eth", source: "ens", configured: true };
+        const missing = [];
+        if (!config.ethRpcUrl)
+            missing.push("ETH_RPC_URL");
+        if (!config.keccak256)
+            missing.push("a keccak256 implementation");
+        return { namespace: "eth", source: "ens", configured: false, reason: `ENS resolution requires ${missing.join(" and ")}` };
+    }
+    async function ethCall(to, data) {
+        const doFetch = config.fetchImpl ?? globalThis.fetch;
+        let res;
+        try {
+            res = await doFetch(config.ethRpcUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to, data }, "latest"] }),
+            });
+        }
+        catch (e) {
+            throw new ResolveError("rpc-error", `ETH RPC request failed: ${String(e)}`);
+        }
+        if (!res.ok)
+            throw new ResolveError("rpc-error", `ETH RPC returned HTTP ${res.status}`);
+        const body = (await res.json());
+        if (body.error)
+            throw new ResolveError("rpc-error", body.error.message ?? "ETH RPC error");
+        return body.result ?? "0x";
+    }
+    return {
+        namespace: "eth",
+        source: "ens",
+        detect(input) {
+            const t = input.trim();
+            const dot = t.lastIndexOf(".");
+            return dot > 0 && t.slice(dot + 1).toLowerCase() === "eth" && !t.startsWith("@");
+        },
+        status,
+        async resolve(input) {
+            const label = externalLabel(input, "eth"); // throws invalid-domain on bad shape
+            if (!configured) {
+                // Gated: a known namespace we cannot reach — typed, never a fabricated address.
+                throw new ResolveError("not-configured", `.eth (ENS) resolution is not enabled on this deployment: ${status().reason}`, input);
+            }
+            const keccak256 = config.keccak256;
+            const name = `${label}.eth`;
+            const node = toHex(ensNamehash(name, keccak256));
+            // 1) registry.resolver(node)
+            const resolverWord = await ethCall(registry, "0x" + SELECTOR_RESOLVER + node);
+            const resolverAddr = addressFromWord(resolverWord);
+            if (!resolverAddr)
+                throw new ResolveError("not-found", `${name} has no resolver set`, input);
+            // 2) resolver.addr(node)
+            const addrWord = await ethCall(resolverAddr, "0x" + SELECTOR_ADDR + node);
+            const address = addressFromWord(addrWord);
+            if (!address)
+                throw new ResolveError("no-record-for-chain", `${name} has no ETH address record`, input);
+            return {
+                input,
+                name,
+                namespace: "eth",
+                address,
+                chain: "ETH",
+                source: "ens",
+                verification: "unverified",
+            };
+        },
+    };
+}

package/dist/universalNative.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Native adapter: `@handle` and X1NS (`.x1` / `.xnt` / `.xen`).
+ *
+ * This is a thin wrapper over the EXISTING on-chain `Resolver` (`createResolver`
+ * in index.ts) — it does not reimplement any resolution. The native path is the
+ * primary and stays entirely unchanged; this adapter only maps the native
+ * `Resolved` onto the universal `{..., source}` shape so it sits alongside the
+ * external adapters uniformly.
+ */
+import type { Resolver } from "./index.js";
+import type { NamespaceAdapter } from "./universalTypes.js";
+/** Build the native adapter from an already-constructed `Resolver`. */
+export declare function createNativeAdapter(resolver: Resolver): NamespaceAdapter;

package/dist/universalNative.js

@@ -0,0 +1,43 @@
+/**
+ * Native adapter: `@handle` and X1NS (`.x1` / `.xnt` / `.xen`).
+ *
+ * This is a thin wrapper over the EXISTING on-chain `Resolver` (`createResolver`
+ * in index.ts) — it does not reimplement any resolution. The native path is the
+ * primary and stays entirely unchanged; this adapter only maps the native
+ * `Resolved` onto the universal `{..., source}` shape so it sits alongside the
+ * external adapters uniformly.
+ */
+import { detectNamespace } from "./universalDetect.js";
+import { NATIVE_NAMESPACES } from "./universalTypes.js";
+/** Build the native adapter from an already-constructed `Resolver`. */
+export function createNativeAdapter(resolver) {
+    return {
+        namespace: NATIVE_NAMESPACES,
+        source: "x1id",
+        detect(input) {
+            try {
+                return NATIVE_NAMESPACES.includes(detectNamespace(input).namespace);
+            }
+            catch {
+                return false;
+            }
+        },
+        status() {
+            // The native resolver is always configured — it reads X1 over the RPC the
+            // resolver was built with (required at construction).
+            return { namespace: NATIVE_NAMESPACES, source: "x1id", configured: true };
+        },
+        async resolve(input, opts) {
+            const res = await resolver.resolve(input, { chain: opts?.chain ?? "X1" });
+            return {
+                input: res.input,
+                name: res.name,
+                namespace: res.namespace,
+                address: res.address,
+                chain: res.chain,
+                source: "x1id",
+                verification: res.verification,
+            };
+        },
+    };
+}

package/dist/universalSns.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SNS adapter — `.sol` domains, read directly from Solana mainnet.
+ *
+ * `.sol` is built on the SPL Name Service program, the same primitive X1NS uses,
+ * so the registry header is identical (parentName(32) | owner(32) | class(32),
+ * then data at offset 96). The differences from the native X1NS read are the
+ * derivation constants and that the name-account PDA needs `find_program_address`
+ * — which this SDK deliberately does not hand-roll (it needs an ed25519 on-curve
+ * check; see wasm.ts). Derivation is therefore an INJECTED dependency: pass your
+ * own {@link SnsDeriver}, or build the default via {@link makeSnsDeriver} (which
+ * uses `@solana/web3.js`).
+ *
+ * Every constant and the header layout were verified BOTH against live Solana
+ * mainnet accounts (bonfida.sol, toly.sol — 2026-10-02) AND against the SNS-SDK
+ * source (github.com/SolanaNameService/sns-sdk `js/src/constants.ts`,
+ * `state.ts`, `nft/const.ts`, `nft/getDomainMint.ts`). Not copied from an
+ * adjacent API surface.
+ *
+ *   bonfida.sol → Crf8hzfthWGbGbLTVCiqRqV5MVnbpHB1L9KQMd6gsinb
+ *     owning program = namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX
+ *     parent = 58PwtjSDuFHuUkYjH9BYnnQKHfwo9reZhC2zMJv9JPkx  (the .sol TLD)
+ *     owner  = Fw1ETanDZafof7xEULsnq9UY6o71Tpds89tNwPkWLb1v
+ *
+ * # Scope of this increment (honest limits)
+ *
+ * We resolve the domain's CURRENT OWNER: the registry `owner` field, OR — when
+ * the domain is wrapped as an NFT — the NFT holder (the registry `owner` of a
+ * wrapped domain is a tokenizer ESCROW PDA, never the human, so returning it
+ * would be a wrong address). We do NOT yet honor SOL payment records (SNS-IP-1
+ * V1 / SNS-IP-3 V2), which can redirect a domain's receive address and carry
+ * their own staleness/signature rules — a documented follow-up. We therefore
+ * return ownership, marked `unverified`.
+ *
+ * # SRS migration watch
+ *
+ * The SNS-SDK `master` ships a new "SRS" (Solana Record Service) resolver under
+ * program `srsWjm76StJucL7atFyPSdXFaVLNPFqEt1uFEDPrZsn`, currently gated OFF
+ * (`SOL_SRS_RESOLUTION_ENABLED = false`, cutoff ~slot 452_825_395, est.
+ * 2026-10-15). Until that flips, the classic NameRegistry path below is the live
+ * resolution path. Revisit after the cutover.
+ */
+import type { NamespaceAdapter } from "./universalTypes.js";
+/** SPL Name Service program on Solana mainnet (owns every `.sol` registry account). */
+export declare const SPL_NAME_PROGRAM_ID = "namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX";
+/** The `.sol` TLD authority — the `nameParent` every root `.sol` domain derives under. */
+export declare const SOL_TLD_AUTHORITY = "58PwtjSDuFHuUkYjH9BYnnQKHfwo9reZhC2zMJv9JPkx";
+/** Prefix hashed with the label to form the SPL Name Service seed. */
+export declare const SNS_HASH_PREFIX = "SPL Name Service";
+/** SNS Name Tokenizer program — wraps a domain into a Metaplex NFT. */
+export declare const NAME_TOKENIZER_ID = "nftD3vbNkNqfj2Sd3HZwbpw4BxxKWr4AjGb9X38JeZk";
+/** Tokenizer mint-PDA seed prefix (`["tokenized_name", nameAccount]`). */
+export declare const SNS_MINT_PREFIX = "tokenized_name";
+/**
+ * The two `find_program_address` derivations SNS resolution needs. Injected so
+ * the SDK core stays free of curve math (and of a hard `@solana/web3.js`
+ * dependency), and so tests can supply deterministic fakes.
+ */
+export interface SnsDeriver {
+    /** Name-account address for a bare `.sol` label (no suffix), base58. */
+    domainKey(label: string): Promise<string> | string;
+    /** Tokenizer mint address for a name-account address, base58. */
+    mintKey(nameAccount: string): Promise<string> | string;
+}
+/**
+ * `hashed_name = sha256(HASH_PREFIX + label)` — the SPL Name Service name hash.
+ * Pure (Web Crypto SHA-256, available in Node 18+ and browsers); no curve math,
+ * so it lives in the SDK and is reused by a deriver as the first PDA seed.
+ */
+export declare function snsHashedName(label: string): Promise<Uint8Array>;
+/**
+ * Build the default SNS deriver using `@solana/web3.js`.
+ *
+ * Seeds (verified live + against the SNS-SDK source):
+ *   domainKey: [ sha256("SPL Name Service"+label), 32 zero bytes (no class),
+ *               SOL_TLD(32) ] under the SPL Name Service program.
+ *   mintKey:   [ "tokenized_name", nameAccount(32) ] under the Name Tokenizer.
+ */
+export declare function makeSnsDeriver(web3Module?: unknown): Promise<SnsDeriver>;
+export interface SnsAdapterConfig {
+    /**
+     * Solana mainnet JSON-RPC endpoint. When absent the adapter is NOT configured
+     * and `resolve` throws `not-configured` — it never falls back to a fabricated
+     * address or silently to a public endpoint.
+     */
+    readonly rpcUrl?: string;
+    /** Optional fetch override (testing / custom transport). */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * The two PDA derivations. Required to resolve; absent → not configured. Build
+     * the default with {@link makeSnsDeriver}, or inject a mock in tests.
+     */
+    readonly deriver?: SnsDeriver;
+}
+/** Build the `.sol` (SNS) adapter. */
+export declare function createSnsAdapter(config?: SnsAdapterConfig): NamespaceAdapter;