@x1id/resolve 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fortiblox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @x1id/resolve
+
+Resolve **`@handles`** and **X1NS** names (`.x1` / `.xnt` / `.xen`) to addresses on
+[X1](https://x1.xyz) — the SDK behind [x1id.io](https://x1id.io).
+
+Built for wallets and payment flows. One rule drives the whole design: **a name
+is never just an address.** `@jack` and `jack.x1` are different namespaces that
+can belong to different people, so every result tells you *which* namespace
+answered, and a mixed shape is refused rather than guessed.
+
+```ts
+import { createResolver, WasmResolver } from "@x1id/resolve";
+
+const wasm = await WasmResolver.fromBytes(/* the module bytes, see below */);
+const x1id = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz", wasm });
+
+const r = await x1id.resolve("@jack");
+// { name: "jack", namespace: "handle", address: "H8Fs…", chain: "X1",
+//   verification: "verified" }
+
+await x1id.resolve("jack.x1");     // resolves the X1NS domain instead
+await x1id.resolve("@jack.x1");    // throws ResolveError { code: "ambiguous" }
+```
+
+## Why a resolver SDK at all
+
+X1NS shipped a great naming service — but with resolution behind their own API.
+A wallet that resolves through a third party's uptime **breaks the day that
+party loses interest**, and every pending payment breaks with it. This SDK never
+calls `api.x1ns.xyz` or any of ours: it **derives accounts and reads them
+straight off chain over RPC**. Point it at any X1 RPC and it works, ours up or
+not.
+
+Address derivation uses a small Rust→WASM module (a real ed25519 on-curve check
+— the kind of thing that is subtly wrong for months when hand-rolled in JS, and
+this is the kind of code that loses money when it is wrong). It is verified
+against live mainnet accounts.
+
+## Install
+
+```bash
+npm install @x1id/resolve
+# or straight from source:
+npm install github:fortiblox/x1id-sdk
+```
+
+`@solana/web3.js` is an **optional** peer dependency — you only need it if you
+pass web3.js types around; the SDK itself talks to RPC directly.
+
+## Loading the WASM module
+
+Derivation needs the WASM module. The package ships it at
+`@x1id/resolve/wasm/x1_resolve_wasm.wasm`.
+
+**Node**
+
+```ts
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { WasmResolver, createResolver } from "@x1id/resolve";
+
+const require = createRequire(import.meta.url);
+const wasmPath = require.resolve("@x1id/resolve/wasm/x1_resolve_wasm.wasm");
+const wasm = await WasmResolver.fromBytes(readFileSync(wasmPath));
+
+const x1id = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz", wasm });
+```
+
+**Browser / bundler**
+
+```ts
+import wasmUrl from "@x1id/resolve/wasm/x1_resolve_wasm.wasm?url"; // Vite
+const wasm = await WasmResolver.fromBytes(await (await fetch(wasmUrl)).arrayBuffer());
+```
+
+## The one rule: show the namespace before you send
+
+`@jack` and `jack.x1` can resolve to **different owners**. There is no API in
+this SDK that returns a bare address — every `Resolved` carries its `namespace`.
+Render it in your recipient field before the user commits a transfer.
+
+```ts
+try {
+  const res = await x1id.resolve(userInput);
+  showRecipient({
+    address: res.address,
+    // e.g. "@jack" or "jack.x1" — the user must see which one they are paying
+    label: res.namespace === "handle" ? `@${res.name}` : res.name,
+    verified: res.verification === "verified",
+  });
+} catch (e) {
+  if (e.code === "not-found") showHint("No name found");
+  else if (e.code === "ambiguous") showHint("Type either @jack or jack.x1, not both");
+  else if (e.code === "invalid-handle") showHint("Letters, digits and hyphens only");
+  // ResolveError.code is always a string a UI can branch on — never a bare throw
+}
+```
+
+See [`examples/recipient-field.ts`](examples/recipient-field.ts) for a fuller
+wallet integration.
+
+## Reverse lookup
+
+```ts
+const name = await x1id.reverse("H8Fs…");   // primary name for an address, or null
+```
+
+## Multi-chain
+
+A handle can carry addresses for several chains. Pass the one you want:
+
+```ts
+await x1id.resolve("@jack", { chain: "X1" });   // default
+await x1id.resolve("@jack", { chain: "SOL" });  // X1 shares Solana's key format
+await x1id.resolve("@jack", { chain: "ETH" });  // → no-record-for-chain (see below)
+```
+
+Today the SDK reads the owner's **X1/SVM** address. Per-chain records for ETH and
+BTC live in separate on-chain accounts the resolver does not read yet, so a
+request for those returns `no-record-for-chain` — an explicit "no record", never
+a wrong address on the wrong chain.
+
+## Verification
+
+| `verification` | meaning |
+|---|---|
+| `verified` | control of the address was proved (the `@handle` owner holds the registry account). |
+| `unverified` | a record exists but ownership was not proved for that chain. **Show a warning.** |
+
+## What works today
+
+| | Status |
+|---|---|
+| X1NS resolution (`.x1/.xnt/.xen`) | ✅ mainnet |
+| `@handle` resolution | ✅ on any RPC where the registry is deployed (testnet today; mainnet on deploy) |
+| Reverse lookup | ✅ |
+| Per-chain ETH/BTC records | 🔜 roadmap |
+| Registration / transfer (write) | 🔜 roadmap |
+
+The `@handle` registry program id is configurable (`handleProgramId`) and
+defaults to the canonical X1 deployment. On an RPC where it is not deployed you
+get an honest `not-found`, never a fabricated address.
+
+## API
+
+```ts
+createResolver(config: ResolverConfig): Resolver
+
+interface ResolverConfig {
+  rpcUrl: string;            // any X1 RPC
+  wasm: WasmResolver;        // required — derivation runs in WASM, no JS fallback
+  fetchImpl?: typeof fetch;  // custom transport (tests, proxies)
+  cacheTtlMs?: number;       // default 30_000; 0 disables
+  handleProgramId?: string;  // default: canonical X1 deployment
+}
+
+interface Resolver {
+  resolve(input: string, opts?: { chain?: "X1" | "SOL" | "ETH" | "BTC" }): Promise<Resolved>;
+  reverse(address: string): Promise<string | null>;
+  clearCache(): void;
+}
+```
+
+`ResolveError.code` is one of: `unrecognized`, `ambiguous`, `invalid-handle`,
+`invalid-domain`, `not-found`, `no-record-for-chain`, `rpc-error`.
+
+## Links
+
+- Home & docs: **[x1id.io](https://x1id.io)**
+- Issues: <https://github.com/fortiblox/x1id-sdk/issues>
+
+## License
+
+MIT © Fortiblox

package/dist/base58.d.ts

@@ -0,0 +1,3 @@
+export declare function encodeBase58(bytes: Uint8Array): string;
+/** Decode to exactly 32 bytes, or null if the input is not a valid address. */
+export declare function decodeBase58_32(s: string): Uint8Array | null;

package/dist/base58.js

@@ -0,0 +1,38 @@
+/** Base58 (Bitcoin alphabet) for 32-byte addresses. */
+const A = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+export function encodeBase58(bytes) {
+    let n = 0n;
+    for (const b of bytes)
+        n = n * 256n + BigInt(b);
+    let out = "";
+    while (n > 0n) {
+        out = A[Number(n % 58n)] + out;
+        n /= 58n;
+    }
+    for (const b of bytes) {
+        if (b !== 0)
+            break;
+        out = "1" + out;
+    }
+    return out === "" ? "1" : out;
+}
+/** Decode to exactly 32 bytes, or null if the input is not a valid address. */
+export function decodeBase58_32(s) {
+    if (s.length === 0 || s.length > 44)
+        return null;
+    let n = 0n;
+    for (const c of s) {
+        const i = A.indexOf(c);
+        if (i === -1)
+            return null;
+        n = n * 58n + BigInt(i);
+    }
+    if (n >= 1n << 256n)
+        return null;
+    const out = new Uint8Array(32);
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(n & 255n);
+        n >>= 8n;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Resolve `@handles` and X1NS names on X1.
+ *
+ * ```ts
+ * import { createResolver } from "@x1id/resolve";
+ *
+ * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz" });
+ * const res = await r.resolve("@jack", { chain: "X1" });
+ * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
+ * ```
+ *
+ * # The one rule
+ *
+ * `@jack` and `jack.x1` are different namespaces that can have **different
+ * owners**. Every result carries its `namespace`, and there is no API returning
+ * a bare address. Render the namespace before letting a user send.
+ *
+ * # Reads chain, not an API
+ *
+ * X1NS names resolve by deriving accounts and reading them over RPC. We never
+ * call `api.x1ns.xyz` — a wallet that resolves through a third party's uptime
+ * breaks when they lose interest.
+ */
+export * from "./types.js";
+export { normalizeHandle, parseName, looksLikeName, type ParsedName } from "./parse.js";
+export { WasmResolver, type WasmTld } from "./wasm.js";
+export { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { type Chain, type Resolved } from "./types.js";
+import { WasmResolver } from "./wasm.js";
+export interface ResolverConfig {
+    /** X1 RPC endpoint. */
+    readonly rpcUrl: string;
+    /**
+     * WASM module for account derivation. Required — derivation needs an
+     * ed25519 on-curve check and there is deliberately no TypeScript fallback,
+     * because a second implementation of that is how wrong addresses get
+     * derived silently.
+     */
+    readonly wasm: WasmResolver;
+    /** Optional fetch override for testing or custom transport. */
+    readonly fetchImpl?: typeof fetch;
+    /** Cache TTL in ms. Default 30_000. Set 0 to disable. */
+    readonly cacheTtlMs?: number;
+    /** @handle registry program id. Defaults to the canonical X1 deployment. */
+    readonly handleProgramId?: string;
+}
+export interface ResolveOptions {
+    /** Which chain's address to return. Default "X1". */
+    readonly chain?: Chain;
+}
+export interface Resolver {
+    /**
+     * Resolve a name to an address on a specific chain.
+     *
+     * @throws {ResolveError} with a `code` a UI can branch on — never a bare
+     * string, so a recipient field can distinguish "still typing" from "this
+     * name does not exist".
+     */
+    resolve(input: string, opts?: ResolveOptions): Promise<Resolved>;
+    /** Reverse: address to its primary name, or null if none is set. */
+    reverse(address: string): Promise<string | null>;
+    /** Clear the resolution cache. */
+    clearCache(): void;
+}
+export declare function createResolver(config: ResolverConfig): Resolver;

package/dist/index.js

@@ -0,0 +1,216 @@
+/**
+ * Resolve `@handles` and X1NS names on X1.
+ *
+ * ```ts
+ * import { createResolver } from "@x1id/resolve";
+ *
+ * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz" });
+ * const res = await r.resolve("@jack", { chain: "X1" });
+ * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
+ * ```
+ *
+ * # The one rule
+ *
+ * `@jack` and `jack.x1` are different namespaces that can have **different
+ * owners**. Every result carries its `namespace`, and there is no API returning
+ * a bare address. Render the namespace before letting a user send.
+ *
+ * # Reads chain, not an API
+ *
+ * X1NS names resolve by deriving accounts and reading them over RPC. We never
+ * call `api.x1ns.xyz` — a wallet that resolves through a third party's uptime
+ * breaks when they lose interest.
+ */
+export * from "./types.js";
+export { normalizeHandle, parseName, looksLikeName } from "./parse.js";
+export { WasmResolver } from "./wasm.js";
+export { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { ResolveError } from "./types.js";
+import { parseName } from "./parse.js";
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Root authority for each X1NS TLD — used to verify a fetched account really
+ *  belongs to the TLD it claims. Without this check a caller handed an
+ *  arbitrary account would read an owner straight out of it. */
+const TLD_ROOT = Object.freeze({
+    x1: "4NG35LXbtyamuoyjarMf5f78esyWxWhSDHxqbAU5yZTk",
+    xnt: "6sHoWK6ht73Pb4y6yA7Sw8iP7DxS45gGp1fH3zWYn56V",
+    xen: "3SUwpSz33AsyJwf6B48cKZuDTswuUEdUhcXszZrFWPqo",
+});
+const SPL_NAME_HEADER_LEN = 96;
+/** The @handle registry program on X1. Deployed on testnet today; the same id
+ *  is used on mainnet once deployed. Override via `handleProgramId` to point at
+ *  a different deployment. */
+const DEFAULT_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
+// Handle account layout, mirrored from the on-chain program:
+//   discriminator(8) name(32) name_len(1) owner(32) ...
+// The owner is the address the handle resolves to on X1.
+const HANDLE_OWNER_OFFSET = 41;
+const HANDLE_MIN_LEN = HANDLE_OWNER_OFFSET + 32;
+export function createResolver(config) {
+    const ttl = config.cacheTtlMs ?? 30_000;
+    const cache = new Map();
+    const doFetch = config.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new Error("No fetch available; pass fetchImpl in ResolverConfig");
+    }
+    const decodedProgram = decodeBase58_32(config.handleProgramId ?? DEFAULT_HANDLE_PROGRAM);
+    if (!decodedProgram) {
+        throw new Error("handleProgramId is not a valid base58 address");
+    }
+    // Explicit type so the non-null narrowing survives into the resolveHandle
+    // closure below — TS widens a captured `const` back to its declared type.
+    const handleProgram = decodedProgram;
+    async function rpc(method, params) {
+        let res;
+        try {
+            res = await doFetch(config.rpcUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+            });
+        }
+        catch (e) {
+            throw new ResolveError("rpc-error", `RPC request failed: ${String(e)}`);
+        }
+        if (!res.ok) {
+            throw new ResolveError("rpc-error", `RPC returned HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new ResolveError("rpc-error", body.error.message ?? "RPC error");
+        }
+        return body.result;
+    }
+    /** Fetch raw account data, or null when the account does not exist. */
+    async function accountData(address) {
+        const result = (await rpc("getAccountInfo", [
+            address,
+            { encoding: "base64" },
+        ]));
+        const value = result?.value;
+        if (!value)
+            return null;
+        const b64 = value.data[0];
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    async function resolveX1ns(canonical, label, tld, chain, input) {
+        const account = config.wasm.deriveX1nsAccount(label, tld);
+        if (!account) {
+            throw new ResolveError("invalid-domain", `"${input}" is not a resolvable label`, input);
+        }
+        const data = await accountData(encodeBase58(account));
+        if (!data) {
+            throw new ResolveError("not-found", `${canonical} is not registered`, input);
+        }
+        if (data.length < SPL_NAME_HEADER_LEN) {
+            throw new ResolveError("rpc-error", `${canonical} returned a malformed account`, input);
+        }
+        // parent_name(32) || owner(32) || class(32)
+        const parent = encodeBase58(data.slice(0, 32));
+        if (parent !== TLD_ROOT[tld]) {
+            // Not a paranoid check: without it, any account could be presented as a
+            // domain and its bytes read as an owner.
+            throw new ResolveError("not-found", `${canonical} is not a .${tld} domain`, input);
+        }
+        const owner = encodeBase58(data.slice(32, 64));
+        // X1NS stores per-chain addresses in a profile record. Until that record is
+        // read, only the owner is known — and the owner is an X1/SVM address.
+        if (chain !== "X1" && chain !== "SOL") {
+            throw new ResolveError("no-record-for-chain", `${canonical} has no ${chain} record`, input);
+        }
+        return {
+            input,
+            name: canonical,
+            namespace: tld,
+            address: owner,
+            chain,
+            // The owner is who controls the name, which is a stronger claim than an
+            // unproved address record — but it is not a per-chain ownership proof.
+            verification: "unverified",
+        };
+    }
+    async function resolveHandle(canonical, chain, input) {
+        const account = config.wasm.deriveHandleAccount(canonical, handleProgram);
+        if (!account) {
+            throw new ResolveError("invalid-handle", `"${input}" is not a valid handle`, input);
+        }
+        const data = await accountData(encodeBase58(account));
+        if (!data) {
+            throw new ResolveError("not-found", `@${canonical} is not registered`, input);
+        }
+        if (data.length < HANDLE_MIN_LEN) {
+            throw new ResolveError("rpc-error", `@${canonical} returned a malformed account`, input);
+        }
+        const owner = encodeBase58(data.slice(HANDLE_OWNER_OFFSET, HANDLE_OWNER_OFFSET + 32));
+        // The owner is an X1/SVM address. Per-chain records (ETH/BTC) live in
+        // separate record accounts the resolver does not read yet, so a request for
+        // another chain is an explicit "no record" rather than a wrong address.
+        if (chain !== "X1" && chain !== "SOL") {
+            throw new ResolveError("no-record-for-chain", `@${canonical} has no ${chain} record`, input);
+        }
+        return {
+            input,
+            name: canonical,
+            namespace: "handle",
+            address: owner,
+            chain,
+            // The owner holds the registry account for this handle — a proved control
+            // relationship, not an unverified record.
+            verification: "verified",
+        };
+    }
+    async function resolve(input, opts) {
+        const chain = opts?.chain ?? "X1";
+        const parsed = parseName(input); // throws with a specific code
+        const key = `${parsed.namespace}:${parsed.canonical}:${chain}`;
+        if (ttl > 0) {
+            const hit = cache.get(key);
+            if (hit && hit.expires > Date.now())
+                return hit.value;
+        }
+        let value;
+        if (parsed.namespace === "handle") {
+            value = await resolveHandle(parsed.canonical, chain, input);
+        }
+        else {
+            value = await resolveX1ns(parsed.canonical, parsed.label, parsed.namespace, chain, input);
+        }
+        if (ttl > 0)
+            cache.set(key, { value, expires: Date.now() + ttl });
+        return value;
+    }
+    /** Address to its primary name, or null when none is set. */
+    async function reverse(address) {
+        const { decodeBase58_32 } = await import("./base58.js");
+        const owner = decodeBase58_32(address);
+        if (!owner)
+            throw new ResolveError("unrecognized", `"${address}" is not an address`, address);
+        const record = config.wasm.derivePrimaryAccount(owner);
+        if (!record)
+            throw new ResolveError("unrecognized", "could not derive record", address);
+        const data = await accountData(encodeBase58(record));
+        if (!data || data.length < 41)
+            return null; // no primary set
+        // tag(1) || domain_account(32) || set_at_i64_le(8)
+        const domainAccount = encodeBase58(data.slice(1, 33));
+        const domainData = await accountData(domainAccount);
+        if (!domainData || domainData.length < SPL_NAME_HEADER_LEN)
+            return null;
+        const parent = encodeBase58(domainData.slice(0, 32));
+        const tld = Object.keys(TLD_ROOT).find((t) => TLD_ROOT[t] === parent);
+        if (!tld)
+            return null;
+        // The account stores no label, so the name cannot be reconstructed from it.
+        // Callers get the TLD and the account; resolving the label needs an index.
+        return `${domainAccount}.${tld}`;
+    }
+    return {
+        resolve,
+        reverse,
+        clearCache: () => cache.clear(),
+    };
+}

package/dist/parse.d.ts

@@ -0,0 +1,37 @@
+import { type Namespace } from "./types.js";
+declare const TLDS: readonly ["x1", "xnt", "xen"];
+export type Tld = (typeof TLDS)[number];
+/**
+ * Canonical handle normalization.
+ *
+ * **This mirrors the Rust `handle-normalize` crate and must stay byte-identical
+ * to it.** The registry derives PDA seeds from the Rust implementation; if this
+ * one diverges, a handle registered under one normalization resolves under
+ * another — permanently unreachable, funds sent nowhere, no error raised.
+ *
+ * The Rust crate is the source of truth. This exists so a browser can give
+ * instant feedback without loading WASM; the conformance suite
+ * (`test/conformance.test.js`) asserts the two agree on every fixture.
+ */
+export declare function normalizeHandle(raw: string): string;
+export interface ParsedName {
+    readonly namespace: Namespace;
+    readonly canonical: string;
+    readonly label: string;
+}
+/**
+ * Classify a name by **shape**, never by trying one namespace and falling back
+ * to the other.
+ *
+ * A fallback chain is exactly how `@jack` and `jack.x1` get conflated, and the
+ * failure mode is silent: the transfer succeeds, to the wrong person.
+ */
+export declare function parseName(input: string): ParsedName;
+/**
+ * Whether input is a name at all, as opposed to a raw address.
+ *
+ * Lets a recipient field decide whether to attempt resolution, so pasting
+ * base58 does not surface a validation error.
+ */
+export declare function looksLikeName(input: string): boolean;
+export {};

package/dist/parse.js

@@ -0,0 +1,92 @@
+import { ResolveError } from "./types.js";
+const TLDS = ["x1", "xnt", "xen"];
+const MAX_HANDLE_LEN = 32;
+/**
+ * Canonical handle normalization.
+ *
+ * **This mirrors the Rust `handle-normalize` crate and must stay byte-identical
+ * to it.** The registry derives PDA seeds from the Rust implementation; if this
+ * one diverges, a handle registered under one normalization resolves under
+ * another — permanently unreachable, funds sent nowhere, no error raised.
+ *
+ * The Rust crate is the source of truth. This exists so a browser can give
+ * instant feedback without loading WASM; the conformance suite
+ * (`test/conformance.test.js`) asserts the two agree on every fixture.
+ */
+export function normalizeHandle(raw) {
+    let s = raw.trim();
+    if (s.startsWith("@"))
+        s = s.slice(1);
+    // ASCII-only. X1NS permits Unicode and emoji; for a payment identifier that
+    // is a homograph vector, since Cyrillic "а" renders identically to ASCII "a".
+    // eslint-disable-next-line no-control-regex
+    if (!/^[\x00-\x7F]*$/.test(s)) {
+        throw new ResolveError("invalid-handle", "Handles must be ASCII only", raw);
+    }
+    if (s.length === 0)
+        throw new ResolveError("invalid-handle", "Handle is empty", raw);
+    if (s.length > MAX_HANDLE_LEN) {
+        throw new ResolveError("invalid-handle", `Handle exceeds ${MAX_HANDLE_LEN} characters`, raw);
+    }
+    const lower = s.toLowerCase();
+    if (!/^[a-z0-9-]+$/.test(lower)) {
+        throw new ResolveError("invalid-handle", "Handles allow only a-z, 0-9 and hyphen", raw);
+    }
+    if (lower.startsWith("-") || lower.endsWith("-")) {
+        throw new ResolveError("invalid-handle", "Handles cannot start or end with a hyphen", raw);
+    }
+    if (lower.includes("--")) {
+        throw new ResolveError("invalid-handle", "Handles cannot contain consecutive hyphens", raw);
+    }
+    if (/^[0-9]+$/.test(lower)) {
+        throw new ResolveError("invalid-handle", "All-digit handles are reserved", raw);
+    }
+    return lower;
+}
+/**
+ * Classify a name by **shape**, never by trying one namespace and falling back
+ * to the other.
+ *
+ * A fallback chain is exactly how `@jack` and `jack.x1` get conflated, and the
+ * failure mode is silent: the transfer succeeds, to the wrong person.
+ */
+export function parseName(input) {
+    const t = input.trim();
+    const looksHandle = t.startsWith("@");
+    const dot = t.lastIndexOf(".");
+    const suffix = dot === -1 ? "" : t.slice(dot + 1).toLowerCase();
+    const looksDomain = TLDS.includes(suffix);
+    if (looksHandle && looksDomain) {
+        throw new ResolveError("ambiguous", `"${t}" is both a handle and a domain shape`, t);
+    }
+    if (looksHandle) {
+        const canonical = normalizeHandle(t);
+        return { namespace: "handle", canonical, label: canonical };
+    }
+    if (looksDomain) {
+        const label = t.slice(0, dot).toLowerCase();
+        if (label.length === 0 || label.includes(".")) {
+            throw new ResolveError("invalid-domain", `"${t}" is not a valid domain`, t);
+        }
+        if (!/^[a-z0-9-]+$/.test(label)) {
+            // X1NS itself permits Unicode here; we refuse to resolve it rather than
+            // render a homograph as a successful result the user will act on.
+            throw new ResolveError("invalid-domain", "Domain labels must be ASCII", t);
+        }
+        return { namespace: suffix, canonical: `${label}.${suffix}`, label };
+    }
+    throw new ResolveError("unrecognized", `"${t}" is not a handle or a known domain`, t);
+}
+/**
+ * Whether input is a name at all, as opposed to a raw address.
+ *
+ * Lets a recipient field decide whether to attempt resolution, so pasting
+ * base58 does not surface a validation error.
+ */
+export function looksLikeName(input) {
+    const t = input.trim();
+    if (t.startsWith("@"))
+        return true;
+    const dot = t.lastIndexOf(".");
+    return dot !== -1 && TLDS.includes(t.slice(dot + 1).toLowerCase());
+}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/** Which naming system produced a result. */
+export type Namespace = "handle" | "x1" | "xnt" | "xen";
+/**
+ * Display label for a namespace. **Must be shown** next to any resolved
+ * address — see the module docs on why this is not optional.
+ */
+export declare function namespaceLabel(ns: Namespace): string;
+/** Confidence in the address a name resolves to. */
+export type Verification = 
+/** Owner proved control of this address for this chain. */
+"verified"
+/** Record exists but ownership was never proved. Show a warning. */
+ | "unverified";
+/**
+ * A successfully resolved name.
+ *
+ * `namespace` is not optional and there is no variant of this type without it.
+ * `@jack` and `jack.x1` are different namespaces with different owners, so a
+ * bare address is never a complete answer.
+ */
+export interface Resolved {
+    /** Exactly what the user typed, for display. */
+    readonly input: string;
+    /** Canonical form of the name. */
+    readonly name: string;
+    /** Which naming system matched. Render this before allowing a send. */
+    readonly namespace: Namespace;
+    /** The address to send to, base58 for X1/SOL, 0x for EVM, bech32 for BTC. */
+    readonly address: string;
+    /** Chain this address belongs to. */
+    readonly chain: Chain;
+    /** Whether ownership of `address` was proved. */
+    readonly verification: Verification;
+}
+/** 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 declare class ResolveError extends Error {
+    readonly code: ResolveErrorCode;
+    readonly input?: string | undefined;
+    constructor(code: ResolveErrorCode, message: string, input?: string | undefined);
+}

package/dist/types.js

@@ -0,0 +1,25 @@
+/**
+ * Display label for a namespace. **Must be shown** next to any resolved
+ * address — see the module docs on why this is not optional.
+ */
+export function namespaceLabel(ns) {
+    return ns === "handle" ? "@handle" : `.${ns}`;
+}
+export const CHAIN_COIN_TYPE = Object.freeze({
+    BTC: 0,
+    ETH: 60,
+    SOL: 501,
+    // X1 shares Solana's SVM and key format; it gets its own record slot so a
+    // user can point X1 and Solana at different wallets if they want to.
+    X1: 501_0000,
+});
+export class ResolveError extends Error {
+    code;
+    input;
+    constructor(code, message, input) {
+        super(message);
+        this.code = code;
+        this.input = input;
+        this.name = "ResolveError";
+    }
+}

package/dist/wasm.d.ts

@@ -0,0 +1,43 @@
+/**
+ * WASM-backed account derivation.
+ *
+ * Derivation needs `find_program_address`, which needs an ed25519 on-curve
+ * check — real curve arithmetic. Rather than hand-roll that in TypeScript
+ * (subtly wrong for months, and this one loses money when it is), the browser
+ * calls the Rust implementation that is already verified against live mainnet
+ * accounts.
+ *
+ * The module is single-threaded by construction: one shared input buffer, one
+ * shared output buffer, call-at-a-time. `WasmResolver` owns an instance and
+ * never yields between writing input and reading output, so callers cannot
+ * interleave.
+ */
+declare const TLD_INDEX: {
+    readonly x1: 0;
+    readonly xnt: 1;
+    readonly xen: 2;
+};
+export type WasmTld = keyof typeof TLD_INDEX;
+export declare class WasmResolver {
+    #private;
+    private constructor();
+    /** Instantiate from raw module bytes. */
+    static fromBytes(bytes: BufferSource): Promise<WasmResolver>;
+    /** Canonical handle form, or null if invalid. */
+    normalizeHandle(raw: string): string | null;
+    /** 32-byte X1NS domain account, or null if the label is invalid. */
+    deriveX1nsAccount(label: string, tld: WasmTld): Uint8Array | null;
+    /** 32-byte primary-domain record account for a 32-byte owner address. */
+    derivePrimaryAccount(owner: Uint8Array): Uint8Array | null;
+    /**
+     * 32-byte `@handle` registry account (a program-derived address) for a
+     * canonical handle under a given registry program id, or null if the handle
+     * is not canonical.
+     *
+     * The program id is staged into a separate WASM buffer first, so the seed
+     * that produces the address is `["handle", canonical]` under exactly the
+     * program the caller names — never a program baked into this module.
+     */
+    deriveHandleAccount(canonical: string, programId: Uint8Array): Uint8Array | null;
+}
+export {};

package/dist/wasm.js

@@ -0,0 +1,75 @@
+/**
+ * WASM-backed account derivation.
+ *
+ * Derivation needs `find_program_address`, which needs an ed25519 on-curve
+ * check — real curve arithmetic. Rather than hand-roll that in TypeScript
+ * (subtly wrong for months, and this one loses money when it is), the browser
+ * calls the Rust implementation that is already verified against live mainnet
+ * accounts.
+ *
+ * The module is single-threaded by construction: one shared input buffer, one
+ * shared output buffer, call-at-a-time. `WasmResolver` owns an instance and
+ * never yields between writing input and reading output, so callers cannot
+ * interleave.
+ */
+const TLD_INDEX = { x1: 0, xnt: 1, xen: 2 };
+export class WasmResolver {
+    #x;
+    #enc = new TextEncoder();
+    #dec = new TextDecoder();
+    constructor(exports) {
+        this.#x = exports;
+    }
+    /** Instantiate from raw module bytes. */
+    static async fromBytes(bytes) {
+        const { instance } = await WebAssembly.instantiate(bytes, {});
+        return new WasmResolver(instance.exports);
+    }
+    #write(bytes) {
+        if (bytes.length > this.#x.input_cap()) {
+            throw new RangeError(`input exceeds ${this.#x.input_cap()} bytes`);
+        }
+        // Re-read the view every call: WebAssembly.Memory can be detached by growth.
+        new Uint8Array(this.#x.memory.buffer, this.#x.input_ptr(), bytes.length).set(bytes);
+        return bytes.length;
+    }
+    #read() {
+        const len = this.#x.output_len();
+        return new Uint8Array(this.#x.memory.buffer, this.#x.output_ptr(), len).slice();
+    }
+    /** Canonical handle form, or null if invalid. */
+    normalizeHandle(raw) {
+        const n = this.#write(this.#enc.encode(raw));
+        return this.#x.normalize_handle(n) === 1 ? this.#dec.decode(this.#read()) : null;
+    }
+    /** 32-byte X1NS domain account, or null if the label is invalid. */
+    deriveX1nsAccount(label, tld) {
+        const n = this.#write(this.#enc.encode(label));
+        return this.#x.derive_x1ns_account(n, TLD_INDEX[tld]) === 1 ? this.#read() : null;
+    }
+    /** 32-byte primary-domain record account for a 32-byte owner address. */
+    derivePrimaryAccount(owner) {
+        if (owner.length !== 32)
+            return null;
+        const n = this.#write(owner);
+        return this.#x.derive_primary_account(n) === 1 ? this.#read() : null;
+    }
+    /**
+     * 32-byte `@handle` registry account (a program-derived address) for a
+     * canonical handle under a given registry program id, or null if the handle
+     * is not canonical.
+     *
+     * The program id is staged into a separate WASM buffer first, so the seed
+     * that produces the address is `["handle", canonical]` under exactly the
+     * program the caller names — never a program baked into this module.
+     */
+    deriveHandleAccount(canonical, programId) {
+        if (programId.length !== 32)
+            return null;
+        // Stage the program id into its own buffer. Re-read the view every call:
+        // WebAssembly.Memory can be detached by growth between calls.
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const n = this.#write(this.#enc.encode(canonical));
+        return this.#x.derive_handle_account_staged(n) === 1 ? this.#read() : null;
+    }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@x1id/resolve",
+  "version": "0.1.0",
+  "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "files": ["dist", "wasm"],
+  "scripts": {
+    "build:wasm": "cargo build --release -p x1-resolve-wasm --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/release/x1_resolve_wasm.wasm wasm/",
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.js",
+    "lint:package": "publint",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["x1", "x1id", "solana", "svm", "naming", "x1ns", "handles", "wallet", "resolver", "web3"],
+  "homepage": "https://x1id.io",
+  "repository": { "type": "git", "url": "git+https://github.com/fortiblox/x1id-sdk.git" },
+  "bugs": { "url": "https://github.com/fortiblox/x1id-sdk/issues" },
+  "license": "MIT",
+  "publishConfig": { "access": "public", "provenance": true },
+  "engines": { "node": ">=18" },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
+    "publint": "^0.2.0"
+  },
+  "peerDependencies": { "@solana/web3.js": "^1.95.0" },
+  "peerDependenciesMeta": { "@solana/web3.js": { "optional": true } }
+}