@x1id/resolve 0.10.0 → 0.12.0

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;

package/dist/universalSns.js

@@ -0,0 +1,223 @@
+/**
+ * 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 { ResolveError } from "./types.js";
+import { encodeBase58, decodeBase58 } from "./base58.js";
+import { makeAccountReader, readU64, bytesEqual, SPL_TOKEN_PROGRAM, TOKEN_ACCOUNT_MIN_LEN, } from "./accounts.js";
+import { externalLabel } from "./universalDetect.js";
+/** SPL Name Service program on Solana mainnet (owns every `.sol` registry account). */
+export const SPL_NAME_PROGRAM_ID = "namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX";
+/** The `.sol` TLD authority — the `nameParent` every root `.sol` domain derives under. */
+export const SOL_TLD_AUTHORITY = "58PwtjSDuFHuUkYjH9BYnnQKHfwo9reZhC2zMJv9JPkx";
+/** Prefix hashed with the label to form the SPL Name Service seed. */
+export const SNS_HASH_PREFIX = "SPL Name Service";
+/** SNS Name Tokenizer program — wraps a domain into a Metaplex NFT. */
+export const NAME_TOKENIZER_ID = "nftD3vbNkNqfj2Sd3HZwbpw4BxxKWr4AjGb9X38JeZk";
+/** Tokenizer mint-PDA seed prefix (`["tokenized_name", nameAccount]`). */
+export const SNS_MINT_PREFIX = "tokenized_name";
+/** SPL Name Service header: parentName(32) | owner(32) | class(32) = 96 bytes, then data. */
+const SPL_NAME_HEADER_LEN = 96;
+/**
+ * `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 async function snsHashedName(label) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new ResolveError("not-configured", "Web Crypto (crypto.subtle) is unavailable for SNS name hashing");
+    }
+    const digest = await subtle.digest("SHA-256", new TextEncoder().encode(SNS_HASH_PREFIX + label));
+    return new Uint8Array(digest);
+}
+/**
+ * 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 async function makeSnsDeriver(web3Module) {
+    // Prefer an INJECTED `@solana/web3.js` module — the robust path when this
+    // package is linked (`file:`/`npm link`), where Node resolves a bare specifier
+    // from THIS package's realpath, not the consumer's node_modules, so the
+    // consumer that owns web3.js (e.g. the dev-api) passes it in. Fall back to a
+    // dynamic import (variable specifier, so tsc never tries to resolve it) for a
+    // normal `npm i @x1id/resolve @solana/web3.js` install.
+    let web3;
+    if (web3Module) {
+        web3 = web3Module;
+    }
+    else {
+        const spec = "@solana/web3.js";
+        try {
+            web3 = (await import(spec));
+        }
+        catch {
+            throw new ResolveError("not-configured", "SNS resolution needs a deriver: install @solana/web3.js, pass the web3 module to makeSnsDeriver, or inject `deriver` in the SNS adapter config");
+        }
+    }
+    const program = new web3.PublicKey(SPL_NAME_PROGRAM_ID);
+    const tld = new web3.PublicKey(SOL_TLD_AUTHORITY).toBytes();
+    const tokenizer = new web3.PublicKey(NAME_TOKENIZER_ID);
+    const prefix = new TextEncoder().encode(SNS_MINT_PREFIX);
+    const zeroClass = new Uint8Array(32);
+    return {
+        async domainKey(label) {
+            const hashed = await snsHashedName(label);
+            const [key] = web3.PublicKey.findProgramAddressSync([hashed, zeroClass, tld], program);
+            return key.toBase58();
+        },
+        mintKey(nameAccount) {
+            const [key] = web3.PublicKey.findProgramAddressSync([prefix, new web3.PublicKey(nameAccount).toBytes()], tokenizer);
+            return key.toBase58();
+        },
+    };
+}
+/** Build the `.sol` (SNS) adapter. */
+export function createSnsAdapter(config = {}) {
+    const reader = config.rpcUrl
+        ? makeAccountReader(config.rpcUrl, config.fetchImpl)
+        : null;
+    const deriver = config.deriver ?? null;
+    function status() {
+        if (!reader) {
+            return { namespace: "sol", source: "sns", configured: false, reason: "no Solana mainnet RPC configured (SOLANA_RPC_URL)" };
+        }
+        if (!deriver) {
+            return { namespace: "sol", source: "sns", configured: false, reason: "no SNS deriver configured (install @solana/web3.js or inject `deriver`)" };
+        }
+        return { namespace: "sol", source: "sns", configured: true };
+    }
+    /**
+     * The NFT holder of a wrapped domain, or null when the domain is not
+     * tokenized. Mirrors the SNS-SDK `retrieveNftOwnerV2`: derive the tokenizer
+     * mint for the name account, take its unique (`amount === 1`) token account,
+     * return that account's SPL-Token owner.
+     */
+    async function nftHolder(rdr, drv, nameAccount) {
+        const mint = await drv.mintKey(nameAccount);
+        // A `.sol` domain is wrapped only if its tokenizer mint account EXISTS. The
+        // common case is an un-wrapped domain, whose derived mint PDA has never been
+        // created — and `getTokenLargestAccounts` on a non-existent account is an RPC
+        // *error* ("could not find account"), NOT an empty result. Letting that error
+        // propagate surfaced as a 502 for ordinary `.sol` names. Probe the mint first:
+        // absent (or not an SPL-Token mint) → the domain is not tokenized, so fall
+        // back to the registry owner; present → it is wrapped, read the NFT holder and
+        // let a genuine RPC failure there remain an rpc-error.
+        const mintInfo = await rdr.accountInfo(mint);
+        if (!mintInfo || mintInfo.owner !== SPL_TOKEN_PROGRAM)
+            return null;
+        const largest = (await rdr.rpc("getTokenLargestAccounts", [mint, { commitment: "confirmed" }]));
+        const holders = (largest?.value ?? []).filter((a) => a.amount === "1");
+        if (holders.length !== 1)
+            return null; // not tokenized / no unique holder
+        const t = await rdr.accountInfo(holders[0].address);
+        if (!t ||
+            t.owner !== SPL_TOKEN_PROGRAM ||
+            t.data.length < TOKEN_ACCOUNT_MIN_LEN ||
+            readU64(t.data, 64) !== 1n) {
+            return null;
+        }
+        const mintBytes = decodeBase58(mint);
+        if (!mintBytes || !bytesEqual(t.data.slice(0, 32), mintBytes))
+            return null;
+        return encodeBase58(t.data.slice(32, 64));
+    }
+    return {
+        namespace: "sol",
+        source: "sns",
+        detect(input) {
+            const t = input.trim();
+            const dot = t.lastIndexOf(".");
+            return dot > 0 && t.slice(dot + 1).toLowerCase() === "sol" && !t.startsWith("@");
+        },
+        status,
+        async resolve(input) {
+            const label = externalLabel(input, "sol"); // throws invalid-domain on bad shape
+            if (!reader || !deriver) {
+                throw new ResolveError("not-configured", `.sol (SNS) resolution is not enabled on this deployment: ${status().reason}`, input);
+            }
+            let accountKey;
+            try {
+                accountKey = await deriver.domainKey(label);
+            }
+            catch (e) {
+                if (e instanceof ResolveError)
+                    throw e;
+                throw new ResolveError("rpc-error", `SNS derivation failed: ${String(e)}`, input);
+            }
+            const acct = await reader.accountInfo(accountKey);
+            if (!acct) {
+                throw new ResolveError("not-found", `${label}.sol is not registered`, input);
+            }
+            // Must be owned by the SPL Name Service program — anyone can fund an
+            // address into existence; its bytes are not a registry record.
+            if (acct.owner !== SPL_NAME_PROGRAM_ID) {
+                throw new ResolveError("not-found", `${label}.sol is not an SNS registry account`, input);
+            }
+            if (acct.data.length < SPL_NAME_HEADER_LEN) {
+                throw new ResolveError("rpc-error", `${label}.sol returned a malformed account`, input);
+            }
+            // Verify the record sits under the .sol TLD — without this an arbitrary SPL
+            // name account could be presented and its bytes read as an owner.
+            if (encodeBase58(acct.data.slice(0, 32)) !== SOL_TLD_AUTHORITY) {
+                throw new ResolveError("not-found", `${label}.sol is not a .sol domain`, input);
+            }
+            // Wrapped domains: the registry `owner` is a tokenizer escrow — resolve the
+            // NFT holder instead, and NEVER return the escrow.
+            const holder = await nftHolder(reader, deriver, accountKey);
+            const address = holder ?? encodeBase58(acct.data.slice(32, 64));
+            return {
+                input,
+                name: `${label}.sol`,
+                namespace: "sol",
+                address,
+                chain: "SOL",
+                source: "sns",
+                // Ownership (registry owner or NFT holder), not a per-chain payment
+                // proof and not yet SOL-record-aware — surfaced conservatively.
+                verification: "unverified",
+            };
+        },
+    };
+}

package/dist/universalTypes.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The X1ID Universal Resolver — shared types.
+ *
+ * X1ID becomes the aggregator: one call resolves a NATIVE `@handle` / X1NS name
+ * AND an external namespace (`.sol` via SNS on Solana, `.eth` via ENS on
+ * Ethereum) by reading each name's OWN chain. Every external namespace is read
+ * directly from its chain over RPC — never through a third party's resolver API,
+ * exactly like the native path's "reads chain, not an API" rule.
+ *
+ * # The one rule still holds
+ *
+ * `@jack`, `jack.x1`, `jack.sol` and `jack.eth` are FOUR different names with
+ * four potentially different owners on three different chains. The universal
+ * resolver classifies by SHAPE and dispatches to exactly one adapter — it never
+ * tries one namespace and falls back to another, and every result carries both
+ * its `namespace` and the `source` system that answered.
+ */
+import type { Chain, Verification } from "./types.js";
+/**
+ * The FIXED namespaces the universal resolver classifies by a known suffix. The
+ * first four are native (resolved by `@x1id/resolve`'s on-chain resolver);
+ * `sol` and `eth` are external adapters. Scoped customer-TLD labels are NOT
+ * here — see {@link UniversalNamespace}.
+ */
+export type FixedNamespace = "handle" | "x1" | "xnt" | "xen" | "sol" | "eth";
+/**
+ * Every namespace a universal result can carry. The fixed six above, PLUS — via
+ * `(string & {})` — an arbitrary SCOPED customer-TLD label (`"testtld"`,
+ * #8484/#8485), which resolves through the native (`source: "x1id"`) path with
+ * `namespace` set to the `.tld`. Literal autocomplete for the fixed six is
+ * preserved; a value that is none of them is a scoped TLD label.
+ */
+export type UniversalNamespace = FixedNamespace | (string & {});
+/** Native X1 namespaces — resolved by the bundled `createResolver`. */
+export declare const NATIVE_NAMESPACES: readonly UniversalNamespace[];
+/**
+ * Which naming SYSTEM produced a result. Orthogonal to `namespace`: `x1`, `xnt`
+ * and `xen` all come from `source: "x1id"`. Carried so an integrator can show
+ * "resolved via SNS" / "resolved via ENS" and reason about trust per system.
+ */
+export type NamespaceSource = "x1id" | "sns" | "ens";
+/**
+ * A normalized, cross-namespace resolution result. Deliberately the same shape
+ * regardless of which chain answered, so a recipient field treats every
+ * namespace uniformly — plus `source` and `verification` so it can label and
+ * warn.
+ */
+export interface UniversalResolved {
+    /** Exactly what the user typed, for display. */
+    readonly input: string;
+    /** Canonical form of the name (e.g. `"jack"`, `"jack.x1"`, `"jack.sol"`). */
+    readonly name: string;
+    /** Which naming system matched. Render this before allowing a send. */
+    readonly namespace: UniversalNamespace;
+    /** The address to send to — base58 for X1/SOL, 0x-hex for ETH. */
+    readonly address: string;
+    /** Chain `address` belongs to. */
+    readonly chain: Chain;
+    /** The system that answered (`x1id` | `sns` | `ens`). */
+    readonly source: NamespaceSource;
+    /**
+     * Whether ownership of `address` was PROVED. External namespaces that only
+     * expose a registry-owner (SNS's registry `owner`, ENS's `addr` record) come
+     * back `unverified` — the address controls/claims the name, which is not the
+     * same as a per-chain ownership proof.
+     */
+    readonly verification: Verification;
+    /**
+     * Optional per-chain / text records, when an adapter supplies them. Omitted in
+     * the first increment for external namespaces (SNS Records V2 / ENS text
+     * records are a follow-up); the field exists so adding them later is additive.
+     */
+    readonly records?: readonly UniversalRecord[];
+}
+/** A single auxiliary record an adapter chose to surface alongside the address. */
+export interface UniversalRecord {
+    /** Record key — a chain symbol (`"ETH"`), coin type, or text key. */
+    readonly key: string;
+    /** Record value as stored (address or free text). */
+    readonly value: string;
+}
+/** Whether an adapter can actually reach its chain on this deployment. */
+export interface AdapterStatus {
+    readonly namespace: UniversalNamespace | readonly UniversalNamespace[];
+    readonly source: NamespaceSource;
+    readonly configured: boolean;
+    /** Human-readable reason when `configured` is false (what env/dep is missing). */
+    readonly reason?: string;
+}
+/** Optional per-call options. `chain` applies only to the native namespaces —
+ *  SNS always answers on SOL and ENS on ETH. */
+export interface UniversalResolveOptions {
+    readonly chain?: Chain;
+}
+/**
+ * A pluggable resolver for one namespace family. Adapters are modular and
+ * independently testable: each owns its own detection, chain read and
+ * normalization, and reports whether it is configured.
+ */
+export interface NamespaceAdapter {
+    /** The namespace(s) this adapter answers for. */
+    readonly namespace: UniversalNamespace | readonly UniversalNamespace[];
+    /** The system this adapter represents. */
+    readonly source: NamespaceSource;
+    /** True iff `input` is shaped for THIS adapter (suffix/prefix classification,
+     *  never a speculative resolve). */
+    detect(input: string): boolean;
+    /** Whether this adapter can reach its chain (RPC + any crypto dep present). */
+    status(): AdapterStatus;
+    /**
+     * Resolve `input` to a normalized result.
+     * @throws {ResolveError} `not-configured` when `status().configured` is false;
+     *   `not-found` / `rpc-error` / shape codes exactly like the native resolver.
+     *   NEVER returns a fabricated address.
+     */
+    resolve(input: string, opts?: UniversalResolveOptions): Promise<UniversalResolved>;
+}

package/dist/universalTypes.js

@@ -0,0 +1,24 @@
+/**
+ * The X1ID Universal Resolver — shared types.
+ *
+ * X1ID becomes the aggregator: one call resolves a NATIVE `@handle` / X1NS name
+ * AND an external namespace (`.sol` via SNS on Solana, `.eth` via ENS on
+ * Ethereum) by reading each name's OWN chain. Every external namespace is read
+ * directly from its chain over RPC — never through a third party's resolver API,
+ * exactly like the native path's "reads chain, not an API" rule.
+ *
+ * # The one rule still holds
+ *
+ * `@jack`, `jack.x1`, `jack.sol` and `jack.eth` are FOUR different names with
+ * four potentially different owners on three different chains. The universal
+ * resolver classifies by SHAPE and dispatches to exactly one adapter — it never
+ * tries one namespace and falls back to another, and every result carries both
+ * its `namespace` and the `source` system that answered.
+ */
+/** Native X1 namespaces — resolved by the bundled `createResolver`. */
+export const NATIVE_NAMESPACES = Object.freeze([
+    "handle",
+    "x1",
+    "xnt",
+    "xen",
+]);