@x1id/resolve 0.1.0 → 0.2.1

package/README.md

@@ -12,7 +12,7 @@ answered, and a mixed shape is refused rather than guessed.
 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 x1id = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
 
 const r = await x1id.resolve("@jack");
 // { name: "jack", namespace: "handle", address: "H8Fs…", chain: "X1",
@@ -20,28 +20,28 @@ const r = await x1id.resolve("@jack");
 
 await x1id.resolve("jack.x1");     // resolves the X1NS domain instead
 await x1id.resolve("@jack.x1");    // throws ResolveError { code: "ambiguous" }
+await x1id.reverse("H8Fs…");       // "nike" — the address's primary @handle, or null
 ```
 
-## Why a resolver SDK at all
+> **Which RPC?** The `@handle` registry is deployed on **X1 testnet** today
+> (`https://rpc.testnet.x1.xyz`). X1NS domains live on **mainnet**
+> (`https://rpc.mainnet.x1.xyz`). Point the resolver at the chain that holds
+> the names you want; on an RPC where the registry is not deployed a handle is
+> an honest `not-found`, never a fabricated address.
 
-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.
+## Where this code lives
 
-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.
+This directory (`sdk/` in the `x1-handles` monorepo) **is the source of
+truth**, published to npm as **`@x1id/resolve`** (MIT). The X1ID app vendors a
+byte-identical copy at `app/src/lib/x1/x1sdk/` (plus the WASM at
+`app/public/x1_resolve_wasm.wasm`) — that copy is a **duplicate, not a
+source**: any change here must be mirrored into `app/src/lib/x1/x1sdk`
+(`test/sync.test.js` fails inside the monorepo when they drift).
 
 ## 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
@@ -50,9 +50,10 @@ 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`.
+`@x1id/resolve/wasm/x1_resolve_wasm.wasm` (an exported subpath, so both
+`require.resolve` and bundler asset imports find it).
 
-**Node**
+**Node (ESM)**
 
 ```ts
 import { readFileSync } from "node:fs";
@@ -63,16 +64,30 @@ 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 });
+const x1id = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
+```
+
+Node ≥ 20.6 can use `import.meta.resolve` instead of `createRequire`:
+
+```ts
+import { fileURLToPath } from "node:url";
+const wasmPath = fileURLToPath(import.meta.resolve("@x1id/resolve/wasm/x1_resolve_wasm.wasm"));
 ```
 
 **Browser / bundler**
 
 ```ts
-import wasmUrl from "@x1id/resolve/wasm/x1_resolve_wasm.wasm?url"; // Vite
+// Vite / Rollup / webpack 5 — the `?url` suffix hands you the asset URL
+import wasmUrl from "@x1id/resolve/wasm/x1_resolve_wasm.wasm?url";
+import { WasmResolver } from "@x1id/resolve";
+
 const wasm = await WasmResolver.fromBytes(await (await fetch(wasmUrl)).arrayBuffer());
 ```
 
+Or copy `node_modules/@x1id/resolve/wasm/x1_resolve_wasm.wasm` into your static
+directory and `fetch("/x1_resolve_wasm.wasm")` it — that is what
+[x1id.io](https://x1id.io) does.
+
 ## The one rule: show the namespace before you send
 
 `@jack` and `jack.x1` can resolve to **different owners**. There is no API in
@@ -96,15 +111,53 @@ try {
 }
 ```
 
-See [`examples/recipient-field.ts`](examples/recipient-field.ts) for a fuller
-wallet integration.
+Dispatch is on shape (`@` prefix vs known TLD suffix), never "try one, fall back
+to the other". `@jack.x1` throws `ambiguous` rather than guessing. Use
+`looksLikeName(input)` to decide whether to attempt resolution at all, so
+pasting base58 does not surface a validation error.
+
+## Reads chain state, not an API
+
+X1NS names resolve by deriving accounts and reading them over RPC. This library
+never calls `api.x1ns.xyz` or any API of ours — a wallet that resolves through
+a third party's uptime breaks when they lose interest. `@handle` resolution
+derives the PDA (`["handle", canonical]` under `handleProgramId`) and reads the
+account directly: an untokenized handle resolves to its `owner`; a tokenized
+one (NFT extension present) resolves to whoever currently holds the handle's
+NFT — the `owner` field is informational once a name is tokenized, and the SDK
+never falls back to it. Reverse lookup reads the registry's on-chain `Primary`
+pointer (`["primary", owner]`). All reads use `confirmed` commitment.
+
+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 accounts in `test/wasm.test.js`.
 
 ## Reverse lookup
 
 ```ts
-const name = await x1id.reverse("H8Fs…");   // primary name for an address, or null
+const name = await x1id.reverse("H8Fs…");
+// "nike"                        → the address's primary @handle (canonical, no "@")
+// "5WL7…dMKK.x1"                → no @handle primary; X1NS primary-domain record
+//                                 (account + TLD — X1NS stores no label on chain)
+// null                          → no primary anywhere
 ```
 
+A `@handle` primary is only returned when it is still trustworthy — the same
+rule the X1ID API and app apply:
+
+1. the `Primary` pointer and the handle it names both exist and are owned by
+   the registry program;
+2. `set_at >= handle.registered_at` — a pointer set before the name's current
+   registration belongs to a previous owner of that name;
+3. the address still holds authority: an untokenized handle's `owner` is the
+   address, or — when the handle is tokenized — the address's associated token
+   account holds exactly 1 of the handle's NFT.
+
+A pointer that fails any rule is treated as absent (falls through to X1NS, then
+`null`), never as an error. Only a malformed *address* throws
+(`ResolveError { code: "unrecognized" }`).
+
 ## Multi-chain
 
 A handle can carry addresses for several chains. Pass the one you want:
@@ -124,22 +177,52 @@ a wrong address on the wrong chain.
 
 | `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.** |
+| `verified` | control of the address was proved: the address owns the `@handle` registry account, or — for a tokenized handle — holds its NFT **in its associated token account** (the only place the registry program recognises as the name's authority, same rule as `reverse()`). |
+| `unverified` | ownership was not proved for that chain (X1NS), or — for a tokenized handle — the NFT is held outside the holder's ATA (an auxiliary account or an escrow): that wallet controls the token but cannot act for the name until it is back in its ATA. **Show a warning.** |
+
+A tokenized handle whose NFT has been **burned** (mint supply 0) resolves to no
+one: `ResolveError { code: "not-found", reason: "nft-burned" }`. The registry
+account's stale `owner` field is never returned for a tokenized handle, on any
+path.
 
 ## 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 | ✅ |
+| `@handle` resolution | ✅ on any RPC where the registry is deployed — **X1 testnet today**; mainnet on deploy |
+| Reverse lookup | ✅ on-chain `@handle` primary (testnet today) with X1NS primary-domain fallback (mainnet); X1NS results are `<domainAccount>.<tld>`, not a label |
 | Per-chain ETH/BTC records | 🔜 roadmap |
-| Registration / transfer (write) | 🔜 roadmap |
+| Registration / transfer / `set_primary` (write) | 🔜 roadmap — use [x1id.io](https://x1id.io) |
 
 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.
+defaults to the canonical X1 deployment
+(`8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P`).
+
+## Errors
+
+`ResolveError` carries a `code` a UI can branch on:
+
+| code | meaning |
+|---|---|
+| `unrecognized` | not a handle or known domain — probably a raw address |
+| `ambiguous` | both shapes at once, e.g. `@jack.x1` |
+| `invalid-handle` / `invalid-domain` | right shape, invalid content |
+| `not-found` | valid name, not registered — or `reason: "nft-burned"`: tokenized and its NFT was burned, so no one holds it |
+| `no-record-for-chain` | registered, but no address for the requested chain |
+| `rpc-error` | transport failure |
+
+## Normalization
+
+`normalizeHandle` mirrors the Rust `handle-normalize` crate, which is the source
+of truth — the on-chain registry derives PDA seeds from it. A conformance suite
+runs both against generated fixtures in CI; divergence fails the build, because
+a divergence would make handles registered under one normalization unreachable
+under the other.
+
+ASCII only, no Unicode or emoji. X1NS permits both; for a payment identifier
+that is a homograph vector (`@аlice` with a Cyrillic `а` renders identically to
+`@alice`).
 
 ## API
 
@@ -147,10 +230,10 @@ get an honest `not-found`, never a fabricated address.
 createResolver(config: ResolverConfig): Resolver
 
 interface ResolverConfig {
-  rpcUrl: string;            // any X1 RPC
+  rpcUrl: string;            // any X1 RPC (testnet for @handles today)
   wasm: WasmResolver;        // required — derivation runs in WASM, no JS fallback
   fetchImpl?: typeof fetch;  // custom transport (tests, proxies)
-  cacheTtlMs?: number;       // default 30_000; 0 disables
+  cacheTtlMs?: number;       // default 30_000; 0 disables (resolve() only)
   handleProgramId?: string;  // default: canonical X1 deployment
 }
 
@@ -159,15 +242,55 @@ interface Resolver {
   reverse(address: string): Promise<string | null>;
   clearCache(): void;
 }
+
+class WasmResolver {
+  static fromBytes(bytes: BufferSource): Promise<WasmResolver>;
+  normalizeHandle(raw: string): string | null;
+  deriveX1nsAccount(label: string, tld: "x1" | "xnt" | "xen"): Uint8Array | null;
+  derivePrimaryAccount(owner: Uint8Array): Uint8Array | null;                       // X1NS primary-domain record
+  deriveHandleAccount(canonical: string, programId: Uint8Array): Uint8Array | null; // ["handle", name]
+  deriveHandlePrimaryAccount(owner: Uint8Array, programId: Uint8Array): Uint8Array | null; // ["primary", owner]
+  deriveAssociatedTokenAccount(owner: Uint8Array, mint: Uint8Array): Uint8Array | null;
+}
+```
+
+Also exported: `parseName`, `looksLikeName`, `normalizeHandle`, `namespaceLabel`,
+`encodeBase58`, `decodeBase58_32`, `ResolveError`, `CHAIN_COIN_TYPE` and the
+types `Resolved`, `Namespace`, `Chain`, `Verification`, `ResolveErrorCode`.
+
+## Developing
+
+```bash
+npm run build:wasm   # cargo build → wasm/x1_resolve_wasm.wasm (needs the wasm32-unknown-unknown target)
+npm run build        # tsc → dist/
+npm test             # node --test; X1_LIVE=1 also runs the testnet reverse() case
 ```
 
-`ResolveError.code` is one of: `unrecognized`, `ambiguous`, `invalid-handle`,
-`invalid-domain`, `not-found`, `no-record-for-chain`, `rpc-error`.
+`wasm/x1_resolve_wasm.wasm` is committed and shipped. Rebuild it whenever
+`crates/x1-resolve-wasm` (or its dependencies) change. A rebuild is **not**
+guaranteed byte-identical: the module published in 0.2.0 (48,765 bytes) differs
+from the monorepo/app copy (48,742 bytes) by 23 bytes — same 13 exports,
+functionally equivalent on every derivation tested (handle PDA, X1NS account,
+primary PDA, ATA, normalize; `test/wasm.test.js` checks them against live
+accounts). Treat the committed binary as the artefact of record and verify by
+running the tests, not by comparing hashes.
+
+## Publishing
+
+Published from the (private) release mirror, not from the monorepo: sync this
+directory (plus `crates/`) there, then push a `v<version>` tag that matches
+`package.json` — the release workflow builds the WASM, runs the tests and
+`publint`, and runs `npm publish`. There is **no provenance attestation** on
+the published package: npm only accepts provenance from public source
+repositories, and the mirror is private. (The README bundled inside 0.2.0
+mentions `--provenance`; that was aspirational — no attestation was ever
+attached, and this file is the accurate statement.)
 
 ## Links
 
 - Home & docs: **[x1id.io](https://x1id.io)**
-- Issues: <https://github.com/fortiblox/x1id-sdk/issues>
+- Developer docs: **[docs.fortiblox.com/docs/x1id](https://docs.fortiblox.com/docs/x1id)**
+- Questions & issues: [x1id.io](https://x1id.io) — contact links in the footer
 
 ## License
 

package/dist/index.d.ts

@@ -2,9 +2,12 @@
  * Resolve `@handles` and X1NS names on X1.
  *
  * ```ts
- * import { createResolver } from "@x1id/resolve";
+ * import { createResolver, WasmResolver } from "@x1id/resolve";
  *
- * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz" });
+ * // bytes of @x1id/resolve/wasm/x1_resolve_wasm.wasm — see the README for loading
+ * const wasm = await WasmResolver.fromBytes(wasmBytes);
+ * // The @handle registry is on X1 testnet today; X1NS domains are on mainnet.
+ * const r = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
  * const res = await r.resolve("@jack", { chain: "X1" });
  * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
  * ```

package/dist/index.js

@@ -2,9 +2,12 @@
  * Resolve `@handles` and X1NS names on X1.
  *
  * ```ts
- * import { createResolver } from "@x1id/resolve";
+ * import { createResolver, WasmResolver } from "@x1id/resolve";
  *
- * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz" });
+ * // bytes of @x1id/resolve/wasm/x1_resolve_wasm.wasm — see the README for loading
+ * const wasm = await WasmResolver.fromBytes(wasmBytes);
+ * // The @handle registry is on X1 testnet today; X1NS domains are on mainnet.
+ * const r = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
  * const res = await r.resolve("@jack", { chain: "X1" });
  * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
  * ```
@@ -43,9 +46,80 @@ const SPL_NAME_HEADER_LEN = 96;
 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.
+// `owner` is the address an UNTOKENIZED handle resolves to. Once the handle
+// is tokenized (NFT extension present, see `parseHandleAccount`) the program
+// treats `owner` as informational only — authority is whoever holds the NFT —
+// and so must every reader.
 const HANDLE_OWNER_OFFSET = 41;
-const HANDLE_MIN_LEN = HANDLE_OWNER_OFFSET + 32;
+// `Handle`'s fixed base allocation (`space = 8 + INIT_SPACE`). The NFT
+// extension, when present, is appended at this boundary regardless of the
+// compact Borsh length of the (variable, `Option`-bearing) struct content —
+// mirrors `Handle::NFT_EXT_OFFSET` in the program and `HANDLE_BASE_LEN` in
+// tools/api.
+const HANDLE_BASE_LEN = 8 + 149;
+// `Primary` pointer account (`["primary", owner]` under the registry):
+//   disc(8) | owner(32) | handle(32) | set_at(i64 LE, 8) | bump(1) = 81 bytes
+const PRIMARY_LEN = 81;
+const PRIMARY_HANDLE_OFFSET = 40;
+const PRIMARY_SET_AT_OFFSET = 72;
+// SPL Token account: mint(32) | owner(32) | amount(u64 LE, 8) | ...
+const TOKEN_ACCOUNT_MIN_LEN = 72;
+// SPL Token mint: mint_authority COption(4+32) | supply(u64 LE, 8) @36 | ...
+const MINT_SUPPLY_OFFSET = 36;
+const MINT_MIN_LEN = MINT_SUPPLY_OFFSET + 8;
+// The registry mints handle NFTs with the legacy SPL Token program, so every
+// token account for a handle mint is owned by it.
+const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+function readI64(data, offset) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(offset, true);
+}
+function readU64(data, offset) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigUint64(offset, true);
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Parse the `Handle` fields the reverse rule needs. Port of `parse_handle` in
+ * tools/api — sequential, because `recovery` / `recovery_target` are
+ * `Option<Pubkey>` (Borsh: tag byte, then 32 bytes when `Some`) and shift
+ * `registered_at`. The NFT mint is read at the fixed base boundary, not the
+ * sequential position.
+ *
+ *   disc(8) name(32) name_len(1) owner(32) handle_type(1)
+ *   recovery: Option<Pubkey>  recovery_initiated_at: i64
+ *   recovery_target: Option<Pubkey>  registered_at: i64  bump(1)
+ *   [at 8+149: nft tag(1) mint(32)]
+ */
+function parseHandleAccount(data) {
+    if (data.length < HANDLE_BASE_LEN)
+        return null;
+    const nameLen = Math.min(data[40], 32);
+    const name = new TextDecoder().decode(data.slice(8, 8 + nameLen));
+    const owner = data.slice(HANDLE_OWNER_OFFSET, HANDLE_OWNER_OFFSET + 32);
+    let pos = 73 + 1; // owner end + handle_type(1)
+    // recovery: Option<Pubkey>
+    if (pos >= data.length)
+        return null;
+    pos += 1 + (data[pos] === 1 ? 32 : 0);
+    pos += 8; // recovery_initiated_at
+    // recovery_target: Option<Pubkey>
+    if (pos >= data.length)
+        return null;
+    pos += 1 + (data[pos] === 1 ? 32 : 0);
+    if (pos + 8 > data.length)
+        return null;
+    const registeredAt = readI64(data, pos);
+    const nftMint = data.length >= HANDLE_BASE_LEN + 33 && data[HANDLE_BASE_LEN] === 1
+        ? data.slice(HANDLE_BASE_LEN + 1, HANDLE_BASE_LEN + 33)
+        : null;
+    return { name, owner, registeredAt, nftMint };
+}
 export function createResolver(config) {
     const ttl = config.cacheTtlMs ?? 30_000;
     const cache = new Map();
@@ -60,6 +134,9 @@ export function createResolver(config) {
     // 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;
+    // Re-encoded (not the caller's string) so a non-canonical base58 spelling of
+    // the same key still compares equal to the RPC's `owner` field.
+    const programBase58 = encodeBase58(handleProgram);
     async function rpc(method, params) {
         let res;
         try {
@@ -81,11 +158,12 @@ export function createResolver(config) {
         }
         return body.result;
     }
-    /** Fetch raw account data, or null when the account does not exist. */
-    async function accountData(address) {
+    /** Fetch raw account data plus the owning program, or null when the account
+     *  does not exist. */
+    async function accountInfo(address) {
         const result = (await rpc("getAccountInfo", [
             address,
-            { encoding: "base64" },
+            { encoding: "base64", commitment: "confirmed" },
         ]));
         const value = result?.value;
         if (!value)
@@ -95,7 +173,11 @@ export function createResolver(config) {
         const out = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             out[i] = bin.charCodeAt(i);
-        return out;
+        return { data: out, owner: value.owner };
+    }
+    /** Fetch raw account data, or null when the account does not exist. */
+    async function accountData(address) {
+        return (await accountInfo(address))?.data ?? null;
     }
     async function resolveX1ns(canonical, label, tld, chain, input) {
         const account = config.wasm.deriveX1nsAccount(label, tld);
@@ -133,35 +215,85 @@ export function createResolver(config) {
             verification: "unverified",
         };
     }
+    /**
+     * Current holder of a tokenized handle: the owner of the single token
+     * account holding the handle's NFT (supply 1, decimals 0). Never falls back
+     * to `Handle.owner` — after the NFT changes hands that field names the
+     * previous owner, and paying it is the exact failure this SDK exists to
+     * prevent.
+     *
+     * Parity with the program's `require_current_authority` (and this
+     * resolver's `reverse()`): the program recognises the holder as the name's
+     * authority only when the NFT sits in the holder's **associated token
+     * account** for the mint. A holder whose NFT is parked elsewhere (an
+     * auxiliary account, a program escrow) still controls the token, so the
+     * address is returned — but as `unverified`, because the registry will not
+     * let that address act for the name until the NFT is back in its ATA.
+     *
+     * A burned NFT (mint supply 0) is `not-found` with reason `nft-burned`: the
+     * name has no holder, and no one — least of all the stale `owner` — may be
+     * paid for it. Any other failure to find the holder is an `rpc-error`.
+     */
+    async function nftHolder(canonical, mint, input) {
+        const mintKey = encodeBase58(mint);
+        const largest = (await rpc("getTokenLargestAccounts", [
+            mintKey,
+            { commitment: "confirmed" },
+        ]));
+        const holders = (largest?.value ?? []).filter((a) => a.amount === "1");
+        if (holders.length !== 1) {
+            const m = await accountInfo(mintKey);
+            if (m &&
+                m.owner === SPL_TOKEN_PROGRAM &&
+                m.data.length >= MINT_MIN_LEN &&
+                readU64(m.data, MINT_SUPPLY_OFFSET) === 0n) {
+                throw new ResolveError("not-found", `@${canonical}'s NFT has been burned — the name has no holder`, input, "nft-burned");
+            }
+            throw new ResolveError("rpc-error", `@${canonical} is tokenized but its NFT has no single holder`, input);
+        }
+        const holdingAccount = holders[0].address;
+        const t = await accountInfo(holdingAccount);
+        if (!t ||
+            t.owner !== SPL_TOKEN_PROGRAM ||
+            t.data.length < TOKEN_ACCOUNT_MIN_LEN ||
+            !bytesEqual(t.data.slice(0, 32), mint) ||
+            readU64(t.data, 64) !== 1n) {
+            throw new ResolveError("rpc-error", `@${canonical} is tokenized but its NFT holder account is malformed`, input);
+        }
+        const holder = t.data.slice(32, 64);
+        const ata = config.wasm.deriveAssociatedTokenAccount(holder, mint);
+        const inAta = ata !== null && encodeBase58(ata) === holdingAccount;
+        return { address: encodeBase58(holder), verification: inAta ? "verified" : "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) {
+        const h = await accountInfo(encodeBase58(account));
+        // An account at the PDA that the registry does not own is not a handle
+        // (anyone can fund an address into existence) — the name is unregistered.
+        if (!h || h.owner !== programBase58) {
             throw new ResolveError("not-found", `@${canonical} is not registered`, input);
         }
-        if (data.length < HANDLE_MIN_LEN) {
+        const handle = parseHandleAccount(h.data);
+        if (!handle) {
             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
+        // The address 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",
-        };
+        // Same authority rule as the program's `require_current_authority` and
+        // this resolver's `reverse()`: untokenized → `Handle.owner` (verified: it
+        // holds the registry account); tokenized → whoever holds the NFT right
+        // now, verified only when it sits in that wallet's ATA (see `nftHolder`).
+        const { address, verification } = handle.nftMint === null
+            ? { address: encodeBase58(handle.owner), verification: "verified" }
+            : await nftHolder(canonical, handle.nftMint, input);
+        return { input, name: canonical, namespace: "handle", address, chain, verification };
     }
     async function resolve(input, opts) {
         const chain = opts?.chain ?? "X1";
@@ -183,12 +315,77 @@ export function createResolver(config) {
             cache.set(key, { value, expires: Date.now() + ttl });
         return value;
     }
-    /** Address to its primary name, or null when none is set. */
+    /**
+     * Reverse resolution through the `@handle` registry's on-chain `Primary`
+     * pointer. Returns the canonical handle name (no `@`), or null when the
+     * address has no pointer or the pointer is no longer trustworthy.
+     *
+     * The read-side rule — identical to `tools/api` `fn reverse`, which is the
+     * reference — trusts a pointer only if all three hold:
+     *   1. the handle account it names exists and is owned by the registry;
+     *   2. `set_at >= handle.registered_at` — a pointer set before the handle's
+     *      current registration belongs to a previous owner of that name;
+     *   3. the address still holds authority: untokenized → `handle.owner ==
+     *      address`; tokenized → ATA(address, mint) exists, its mint/owner match
+     *      and its amount is exactly 1.
+     * A pointer that fails any rule is treated as absent, never as an error: it
+     * is a stale artefact the owner can `clear_primary`, not a malformed chain.
+     */
+    async function reverseHandle(owner) {
+        const pointer = config.wasm.deriveHandlePrimaryAccount(owner, handleProgram);
+        if (!pointer)
+            return null;
+        const p = await accountInfo(encodeBase58(pointer));
+        if (!p || p.data.length < PRIMARY_LEN || p.owner !== programBase58)
+            return null;
+        const handleKey = encodeBase58(p.data.slice(PRIMARY_HANDLE_OFFSET, PRIMARY_HANDLE_OFFSET + 32));
+        const setAt = readI64(p.data, PRIMARY_SET_AT_OFFSET);
+        // rule 1: the handle is live and a registry account.
+        const h = await accountInfo(handleKey);
+        if (!h || h.owner !== programBase58)
+            return null;
+        const handle = parseHandleAccount(h.data);
+        if (!handle)
+            return null;
+        // rule 2: staleness — the pointer must be at least as new as the handle.
+        if (setAt < handle.registeredAt)
+            return null;
+        // rule 3: authority still matches.
+        if (handle.nftMint === null) {
+            if (!bytesEqual(handle.owner, owner))
+                return null;
+        }
+        else {
+            const ata = config.wasm.deriveAssociatedTokenAccount(owner, handle.nftMint);
+            if (!ata)
+                return null;
+            const t = await accountInfo(encodeBase58(ata));
+            if (!t || t.data.length < TOKEN_ACCOUNT_MIN_LEN)
+                return null;
+            const mintOk = bytesEqual(t.data.slice(0, 32), handle.nftMint);
+            const ownerOk = bytesEqual(t.data.slice(32, 64), owner);
+            const amount = readU64(t.data, 64);
+            if (!mintOk || !ownerOk || amount !== 1n)
+                return null;
+        }
+        return handle.name;
+    }
+    /**
+     * Address to its primary name, or null when none is set.
+     *
+     * Two sources, in order: the `@handle` registry's on-chain `Primary` pointer
+     * (returned as the plain canonical handle, e.g. `"nike"`), then — only when
+     * there is no valid handle primary — X1NS's primary-domain record, returned
+     * as `"<domainAccount>.<tld>"` exactly as before. The handle path never
+     * throws for a stale or dangling pointer; it falls through to X1NS instead.
+     */
     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 handleName = await reverseHandle(owner);
+        if (handleName !== null)
+            return handleName;
         const record = config.wasm.derivePrimaryAccount(owner);
         if (!record)
             throw new ResolveError("unrecognized", "could not derive record", address);

package/dist/types.d.ts

@@ -36,8 +36,19 @@ export interface Resolved {
 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";
+/**
+ * Finer-grained cause for a `ResolveError`, when the code alone is not
+ * enough for a UI to explain what happened.
+ *
+ * - `nft-burned`: the handle is tokenized and its NFT has been burned (mint
+ *   supply 0), so nobody holds authority over the name any more. Surfaces
+ *   as `not-found` — the name resolves to no one — never as the registry
+ *   account's stale `owner` field.
+ */
+export type ResolveErrorReason = "nft-burned";
 export declare class ResolveError extends Error {
     readonly code: ResolveErrorCode;
     readonly input?: string | undefined;
-    constructor(code: ResolveErrorCode, message: string, input?: string | undefined);
+    readonly reason?: ResolveErrorReason | undefined;
+    constructor(code: ResolveErrorCode, message: string, input?: string | undefined, reason?: ResolveErrorReason | undefined);
 }

package/dist/types.js

@@ -16,10 +16,12 @@ export const CHAIN_COIN_TYPE = Object.freeze({
 export class ResolveError extends Error {
     code;
     input;
-    constructor(code, message, input) {
+    reason;
+    constructor(code, message, input, reason) {
         super(message);
         this.code = code;
         this.input = input;
+        this.reason = reason;
         this.name = "ResolveError";
     }
 }

package/dist/wasm.d.ts

@@ -39,5 +39,20 @@ export declare class WasmResolver {
      * program the caller names — never a program baked into this module.
      */
     deriveHandleAccount(canonical: string, programId: Uint8Array): Uint8Array | null;
+    /**
+     * 32-byte `@handle` registry `Primary` pointer account for a 32-byte owner
+     * address under a given registry program id — seeds `["primary", owner]`.
+     * This is the on-chain `set_primary` / `clear_primary` PDA, NOT X1NS's
+     * primary-domain record (`derivePrimaryAccount`), which lives under the
+     * X1NS registrar and has a different layout.
+     */
+    deriveHandlePrimaryAccount(owner: Uint8Array, programId: Uint8Array): Uint8Array | null;
+    /**
+     * 32-byte SPL associated token account for `(owner, mint)` under the
+     * canonical SPL Token + Associated Token programs (fixed inside the module —
+     * they are the same on every SVM chain). Used to check that an address still
+     * holds a tokenized handle's NFT.
+     */
+    deriveAssociatedTokenAccount(owner: Uint8Array, mint: Uint8Array): Uint8Array | null;
 }
 export {};

package/dist/wasm.js

@@ -72,4 +72,33 @@ export class WasmResolver {
         const n = this.#write(this.#enc.encode(canonical));
         return this.#x.derive_handle_account_staged(n) === 1 ? this.#read() : null;
     }
+    /**
+     * 32-byte `@handle` registry `Primary` pointer account for a 32-byte owner
+     * address under a given registry program id — seeds `["primary", owner]`.
+     * This is the on-chain `set_primary` / `clear_primary` PDA, NOT X1NS's
+     * primary-domain record (`derivePrimaryAccount`), which lives under the
+     * X1NS registrar and has a different layout.
+     */
+    deriveHandlePrimaryAccount(owner, programId) {
+        if (owner.length !== 32 || programId.length !== 32)
+            return null;
+        new Uint8Array(this.#x.memory.buffer, this.#x.program_ptr(), 32).set(programId);
+        const n = this.#write(owner);
+        return this.#x.derive_handle_primary_account_staged(n) === 1 ? this.#read() : null;
+    }
+    /**
+     * 32-byte SPL associated token account for `(owner, mint)` under the
+     * canonical SPL Token + Associated Token programs (fixed inside the module —
+     * they are the same on every SVM chain). Used to check that an address still
+     * holds a tokenized handle's NFT.
+     */
+    deriveAssociatedTokenAccount(owner, mint) {
+        if (owner.length !== 32 || mint.length !== 32)
+            return null;
+        const joined = new Uint8Array(64);
+        joined.set(owner, 0);
+        joined.set(mint, 32);
+        const n = this.#write(joined);
+        return this.#x.derive_associated_token_account(n) === 1 ? this.#read() : null;
+    }
 }

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./wasm/x1_resolve_wasm.wasm": "./wasm/x1_resolve_wasm.wasm",
+    "./wasm/*": "./wasm/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "wasm",
+    "README.md"
+  ],
   "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",
@@ -14,18 +26,37 @@
     "lint:package": "publint",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["x1", "x1id", "solana", "svm", "naming", "x1ns", "handles", "wallet", "resolver", "web3"],
+  "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" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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 } }
+  "peerDependencies": {
+    "@solana/web3.js": "^1.95.0"
+  },
+  "peerDependenciesMeta": {
+    "@solana/web3.js": {
+      "optional": true
+    }
+  }
 }