@x1id/resolve 0.2.0 → 0.2.1

package/README.md

@@ -122,8 +122,11 @@ 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
-owner directly; reverse lookup reads the registry's on-chain `Primary` pointer
-(`["primary", owner]`). All reads use `confirmed` commitment.
+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
@@ -174,8 +177,13 @@ 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
 
@@ -200,7 +208,7 @@ defaults to the canonical X1 deployment
 | `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 |
+| `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 |
 
@@ -259,15 +267,24 @@ npm test             # node --test; X1_LIVE=1 also runs the testnet reverse() ca
 ```
 
 `wasm/x1_resolve_wasm.wasm` is committed and shipped. Rebuild it whenever
-`crates/x1-resolve-wasm` (or its dependencies) change; the release profile is
-stripped, so a rebuild from the same source is byte-identical.
+`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 --provenance`.
+`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
 

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,11 @@ 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 —
@@ -59,6 +64,12 @@ 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);
 }
@@ -204,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";

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/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.2.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" },
+    ".": {
+      "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"],
+  "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",
@@ -19,16 +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",
   "license": "MIT",
-  "publishConfig": { "access": "public" },
-  "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
+    }
+  }
 }