@x1id/resolve 0.11.0 → 0.12.0

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",
+]);

package/dist/wasm.d.ts

@@ -78,5 +78,22 @@ export declare class WasmResolver {
      * Needed on BOTH sides of a `ProgrammableNonFungible` transfer.
      */
     deriveTokenRecordAccount(mint: Uint8Array, token: Uint8Array, programId: Uint8Array): Uint8Array | null;
+    /**
+     * Derive the per-handle `NamespaceOverride` PDA under the registry program id
+     * — seeds `["namespace_override", handle, label]`, matching the on-chain
+     * `CreateNamespaceOverride` account. `handle` is the 32-byte handle PDA
+     * (from {@link deriveHandleAccount}); `label` is the namespace label (e.g.
+     * "xnt"), 1..=16 bytes. Returns the 32-byte override account, or null.
+     *
+     * NOTE: overrides are built but not yet honored by `resolve()` — this derive
+     * is for the write builders (namespaceOverride.ts) and the gated read path.
+     */
+    /**
+     * Derive a `Namespace` directory PDA under the registry program id — seeds
+     * `["namespace", label]`. Needed to pass the namespace account into a
+     * create-override instruction. `label` is 1..=16 bytes. Returns 32 bytes or null.
+     */
+    deriveNamespaceAccount(label: string, programId: Uint8Array): Uint8Array | null;
+    deriveNamespaceOverrideAccount(handle: Uint8Array, label: string, programId: Uint8Array): Uint8Array | null;
 }
 export {};

package/dist/wasm.js

@@ -146,4 +146,42 @@ export class WasmResolver {
         const n = this.#write(joined);
         return this.#x.derive_token_record_account(n) === 1 ? this.#read() : null;
     }
+    /**
+     * Derive the per-handle `NamespaceOverride` PDA under the registry program id
+     * — seeds `["namespace_override", handle, label]`, matching the on-chain
+     * `CreateNamespaceOverride` account. `handle` is the 32-byte handle PDA
+     * (from {@link deriveHandleAccount}); `label` is the namespace label (e.g.
+     * "xnt"), 1..=16 bytes. Returns the 32-byte override account, or null.
+     *
+     * NOTE: overrides are built but not yet honored by `resolve()` — this derive
+     * is for the write builders (namespaceOverride.ts) and the gated read path.
+     */
+    /**
+     * Derive a `Namespace` directory PDA under the registry program id — seeds
+     * `["namespace", label]`. Needed to pass the namespace account into a
+     * create-override instruction. `label` is 1..=16 bytes. Returns 32 bytes or null.
+     */
+    deriveNamespaceAccount(label, programId) {
+        if (programId.length !== 32)
+            return null;
+        const labelBytes = this.#enc.encode(label);
+        if (labelBytes.length < 1 || labelBytes.length > 16)
+            return null;
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const n = this.#write(labelBytes);
+        return this.#x.derive_namespace_account(n) === 1 ? this.#read() : null;
+    }
+    deriveNamespaceOverrideAccount(handle, label, programId) {
+        if (handle.length !== 32 || programId.length !== 32)
+            return null;
+        const labelBytes = this.#enc.encode(label);
+        if (labelBytes.length < 1 || labelBytes.length > 16)
+            return null;
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const joined = new Uint8Array(32 + labelBytes.length);
+        joined.set(handle, 0);
+        joined.set(labelBytes, 32);
+        const n = this.#write(joined);
+        return this.#x.derive_namespace_override_account(n) === 1 ? this.#read() : null;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",