@x1id/resolve 0.2.0 → 0.3.0

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
@@ -160,22 +163,46 @@ A pointer that fails any rule is treated as absent (falls through to X1NS, then
 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: "X1" });   // default — the handle's authority
 await x1id.resolve("@jack", { chain: "SOL" });  // X1 shares Solana's key format
-await x1id.resolve("@jack", { chain: "ETH" });  // → no-record-for-chain (see below)
+await x1id.resolve("@jack", { chain: "ETH" });  // the handle's ETH record, if one is set
+await x1id.resolve("@jack", { chain: "BTC" });  // the handle's BTC record, if one is set
 ```
 
-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.
+For **X1/SOL** the SDK returns the handle's current authority. For **ETH/BTC**
+it reads the handle's per-chain `Record` accounts; a handle without a live
+record for the requested chain is `no-record-for-chain` — an explicit "no
+record", never a wrong address on the wrong chain.
+
+Every record is judged against the **universal staleness rule**
+(`docs/record-trust.md` in the x1-handles repo): a `Record` whose
+`updated_at` predates the handle's current `registered_at` was left behind by
+a **previous owner of the same name** (the Handle PDA survives a release +
+re-register, and records hang off it) and is treated as unset — its address
+is never resolved, and its stored `verified: true` is never surfaced. The
+rule is structural in this SDK: `decodeRecord`/`fetchRecords` require the
+handle's `registeredAt`, so there is no code path that returns an unjudged
+record.
+
+```ts
+// All records of a handle, stale ones flagged (verified forced false):
+const all = await x1id.records("@jack");
+// The ones that actually belong to the current owner:
+import { liveRecords } from "@x1id/resolve";
+const live = liveRecords(all);
+```
 
 ## 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.** |
+| `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
 
@@ -184,13 +211,83 @@ a wrong address on the wrong chain.
 | X1NS resolution (`.x1/.xnt/.xen`) | ✅ mainnet |
 | `@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 |
+| Per-chain ETH/BTC records | ✅ read with the staleness rule enforced structurally |
+| Control proofs (prove you control a `@handle`) | ✅ `createControlChallenge` / `verifyControlProof` — spec: `docs/control-proof.md` |
+| Records read (per-chain, staleness-enforced) | ✅ `fetchRecords` |
+| Subnames · gifts · integrator rev-share · name-lock · record-delegate · text records · attestations (write) | ✅ 0.3.0 — instruction builders; you sign & relay |
 | 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
 (`8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P`).
 
+## Beyond resolve: the registry write surface (0.3.0)
+
+`resolve()` / `reverse()` / `fetchRecords()` are read-only and need only an RPC.
+0.3.0 also ships **instruction builders** for the on-chain registry. Each
+returns an unsigned `BuiltInstruction` (`{ programId, keys, data }`) — you
+assemble it into a transaction, **sign, and relay** yourself; the SDK never
+holds keys. Every discriminator and account order matches the deployed program.
+
+**Read a handle's cross-chain records** (no wallet):
+
+```ts
+import { fetchRecords, liveRecords, valueToAddress } from "@x1id/resolve";
+
+// handleAccount = the ["handle", name] PDA; registeredAt from the handle account
+const records = await fetchRecords(rpc, programId, handleAccount, registeredAt);
+for (const r of liveRecords(records)) {
+  console.log(r.chain, valueToAddress(r.chain, r.value));
+}
+```
+
+**Issue a subname** (`team.you`), signed by the parent's current authority:
+
+```ts
+import { buildCreateSubnameIx } from "@x1id/resolve";
+
+const ix = buildCreateSubnameIx({
+  programId,
+  payer,      // signer — funds the subname account's rent
+  owner,      // signer — the parent handle's current authority (owner or NFT holder)
+  parent,     // the parent ["handle", name] PDA
+  subname,    // the ["subname", parent, label] PDA
+  label: "team",
+});
+// add `ix` to a transaction, sign with payer + owner, send.
+```
+
+**Gift a handle** (prepaid voucher; the recipient claims it later):
+
+```ts
+import { buildCreateVoucherIx, HandleType } from "@x1id/resolve";
+
+const ix = buildCreateVoucherIx({
+  programId, payer, config,   // config = the ["config"] PDA
+  voucher,                    // the ["voucher", name] PDA
+  handle,                     // the ["handle", name] PDA — must be unregistered
+  name: "gift1",
+  handleType: HandleType.Human,
+  recipient,                  // bind to a wallet, or null for an open claim code
+  expiresAt: Math.floor(Date.now() / 1000) + 30 * 86400,
+});
+```
+
+Also shipped, same build → sign → relay shape:
+
+| Capability | Builders |
+|---|---|
+| Integrator rev-share | `buildAddIntegratorIx`, `buildSetIntegratorRateIx`, `buildRemoveIntegratorIx` |
+| Name lock / timelocked unlock | `buildLockHandleIx`, `buildInitiateUnlockIx`, `buildCompleteUnlockIx`, `buildCancelUnlockIx` |
+| Record-write delegation | `buildSetRecordDelegateIx`, `buildRevokeRecordDelegateIx` |
+| Typed text records (website / avatar / socials) | `buildCreateTextRecordIx`, `buildUpdateTextRecordIx`, `buildCloseTextRecordIx` |
+| Domain / social attestations | `buildCreateAttestationIx`, `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`) |
+| Subname records / revoke | `buildRevokeSubnameIx`, `buildCreateSubnameRecordIx`, `buildUpdateSubnameRecordIx`, `buildCloseSubnameRecordIx` |
+| Voucher claim / refund | `buildClaimVoucherIx`, `buildRefundVoucherIx` |
+
+PDA seeds and account layouts are documented per module in the source and typed
+end to end. Reads need only an RPC; writes need a signer.
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:
@@ -200,7 +297,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 |
 
@@ -232,6 +329,7 @@ interface ResolverConfig {
 interface Resolver {
   resolve(input: string, opts?: { chain?: "X1" | "SOL" | "ETH" | "BTC" }): Promise<Resolved>;
   reverse(address: string): Promise<string | null>;
+  records(input: string): Promise<readonly HandleRecord[]>; // stale ones flagged — see docs/record-trust.md
   clearCache(): void;
 }
 
@@ -250,6 +348,39 @@ Also exported: `parseName`, `looksLikeName`, `normalizeHandle`, `namespaceLabel`
 `encodeBase58`, `decodeBase58_32`, `ResolveError`, `CHAIN_COIN_TYPE` and the
 types `Resolved`, `Namespace`, `Chain`, `Verification`, `ResolveErrorCode`.
 
+Records: `decodeRecord(raw, account, registeredAt)`, `liveRecords`,
+`chainForCoinType`, `valueToAddress`, `fetchRecords`, `RECORD_LEN`,
+`RECORD_DISC`, type `HandleRecord`. The handle epoch (`registeredAt`) is a
+required parameter everywhere by design.
+
+Control proofs (spec: `docs/control-proof.md` in the x1-handles repo):
+
+```ts
+// Verifier side — reads the handle's current ownership epoch from chain,
+// generates a single-use nonce, returns the challenge to store and send:
+const issued = await createControlChallenge({ rpcUrl, wasm }, "@jack");
+// Prover signs the raw UTF-8 bytes of issued.challenge with the wallet key
+// that controls the handle (64-byte ed25519, no wallet envelope), then:
+const result = await verifyControlProof({ rpcUrl, wasm }, issued, { signer, signature });
+// result.valid === true ⇔ signer controls @jack right now, in this epoch.
+```
+
+Also exported for that flow: `buildControlChallenge`, `parseControlChallenge`,
+`generateControlNonce`, `verifyEd25519Strict` (RFC-8032-strict WebCrypto
+verifier; override via `ControlConfig.verifyEd25519` on runtimes without
+Ed25519 WebCrypto), `CONTROL_CHALLENGE_PREFIX` and the types
+`ControlChallenge`, `ControlConfig`, `ControlProof`, `ControlVerification`,
+`ControlFailureReason`.
+
+## Integrating into a wallet or explorer
+
+Dropping resolution into someone else's product — an explorer that shows
+`@handle` instead of an address, a wallet that resolves a recipient before it
+signs, an in-wallet (Snap-style) resolver — is a copy-paste job. See
+**[`docs/resolution-integration.md`](../docs/resolution-integration.md)**: a
+resolver singleton, a typed-error recipient flow, reverse lookup with the
+staleness rule, and a ~30-line React `<AddressName>`, all against this package.
+
 ## Developing
 
 ```bash
@@ -259,15 +390,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/accounts.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `@handle` registry account access shared by the resolver (`index.ts`), the
+ * per-chain record reader (`records.ts`) and the control-proof helpers
+ * (`control.ts`). One implementation of the byte layouts and of the
+ * "who currently holds authority" rule, so the three surfaces cannot drift.
+ *
+ * Everything here was extracted verbatim from `index.ts` (where the resolver
+ * tests exercise it); nothing in this module is public API on its own.
+ */
+import { type Verification } from "./types.js";
+import type { WasmResolver } from "./wasm.js";
+/** 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. */
+export declare const DEFAULT_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
+export declare const TOKEN_ACCOUNT_MIN_LEN = 72;
+export declare const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+/** The fields of a `Handle` account readers need. */
+export interface ParsedHandle {
+    readonly name: string;
+    readonly owner: Uint8Array;
+    /**
+     * `Handle.registered_at` — the handle's CURRENT ownership epoch. Stamped
+     * fresh on every `register`/`register_reserved`, including a re-registration
+     * of a previously released name, and bumped by every native-market sale.
+     * Every per-handle record and proof must be judged against it — see
+     * docs/record-trust.md.
+     */
+    readonly registeredAt: bigint;
+    /** Set when the handle is tokenized (NFT extension present). */
+    readonly nftMint: Uint8Array | null;
+}
+export declare function readI64(data: Uint8Array, offset: number): bigint;
+export declare function readU64(data: Uint8Array, offset: number): bigint;
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Parse the `Handle` fields readers need. 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)]
+ */
+export declare function parseHandleAccount(data: Uint8Array): ParsedHandle | null;
+/** A JSON-RPC call against the configured endpoint. */
+export type RpcFn = (method: string, params: unknown[]) => Promise<unknown>;
+export interface AccountReader {
+    readonly rpc: RpcFn;
+    /** Fetch raw account data plus the owning program, or null when the account
+     *  does not exist. */
+    accountInfo(address: string): Promise<{
+        readonly data: Uint8Array;
+        readonly owner: string;
+    } | null>;
+    /** Fetch raw account data, or null when the account does not exist. */
+    accountData(address: string): Promise<Uint8Array | null>;
+}
+/** Build the RPC plumbing every reader in this package shares. */
+export declare function makeAccountReader(rpcUrl: string, fetchImpl?: typeof fetch): AccountReader;
+/**
+ * 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 the
+ * 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`.
+ */
+export declare function nftHolder(reader: AccountReader, wasm: WasmResolver, canonical: string, mint: Uint8Array, input: string): Promise<{
+    readonly address: string;
+    readonly verification: Verification;
+}>;

package/dist/accounts.js

@@ -0,0 +1,183 @@
+/**
+ * `@handle` registry account access shared by the resolver (`index.ts`), the
+ * per-chain record reader (`records.ts`) and the control-proof helpers
+ * (`control.ts`). One implementation of the byte layouts and of the
+ * "who currently holds authority" rule, so the three surfaces cannot drift.
+ *
+ * Everything here was extracted verbatim from `index.ts` (where the resolver
+ * tests exercise it); nothing in this module is public API on its own.
+ */
+import { ResolveError } from "./types.js";
+import { encodeBase58 } from "./base58.js";
+/** 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. */
+export const DEFAULT_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
+// Handle account layout, mirrored from the on-chain program:
+//   discriminator(8) name(32) name_len(1) owner(32) ...
+// `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;
+// `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;
+// SPL Token account: mint(32) | owner(32) | amount(u64 LE, 8) | ...
+export 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.
+export const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export function readI64(data, offset) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(offset, true);
+}
+export function readU64(data, offset) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigUint64(offset, true);
+}
+export 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 readers need. 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)]
+ */
+export 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 };
+}
+/** Build the RPC plumbing every reader in this package shares. */
+export function makeAccountReader(rpcUrl, fetchImpl) {
+    const doFetch = fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new Error("No fetch available; pass fetchImpl in the config");
+    }
+    async function rpc(method, params) {
+        let res;
+        try {
+            res = await doFetch(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;
+    }
+    async function accountInfo(address) {
+        const result = (await rpc("getAccountInfo", [
+            address,
+            { encoding: "base64", commitment: "confirmed" },
+        ]));
+        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 { data: out, owner: value.owner };
+    }
+    async function accountData(address) {
+        return (await accountInfo(address))?.data ?? null;
+    }
+    return { rpc, accountInfo, accountData };
+}
+/**
+ * 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 the
+ * 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`.
+ */
+export async function nftHolder(reader, wasm, canonical, mint, input) {
+    const mintKey = encodeBase58(mint);
+    const largest = (await reader.rpc("getTokenLargestAccounts", [
+        mintKey,
+        { commitment: "confirmed" },
+    ]));
+    const holders = (largest?.value ?? []).filter((a) => a.amount === "1");
+    if (holders.length !== 1) {
+        const m = await reader.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 reader.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 = wasm.deriveAssociatedTokenAccount(holder, mint);
+    const inAta = ata !== null && encodeBase58(ata) === holdingAccount;
+    return { address: encodeBase58(holder), verification: inAta ? "verified" : "unverified" };
+}