@x1id/resolve 0.2.1 → 0.6.0

package/README.md

@@ -163,15 +163,34 @@ 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
 
@@ -192,13 +211,210 @@ path.
 | 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.
+```
+
+**Register a handle** (pays whatever the on-chain ramp charges as of the
+landing slot — there is no client-supplied price):
+
+```ts
+import { buildRegisterIx, fetchConfigTreasury, HandleType } from "@x1id/resolve";
+
+const treasury = await fetchConfigTreasury(rpc, configAccount); // Config.treasury, read fresh
+const ix = buildRegisterIx({
+  programId, payer, owner,
+  config: configAccount,       // the ["config"] PDA
+  treasury,
+  handle,                      // the ["handle", name] PDA — must be unregistered
+  name: "payday-bot",
+  handleType: HandleType.Agent,
+});
+```
+
+**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` |
+| Register a handle | `buildRegisterIx` (+ `fetchConfigTreasury`) |
+| Verify a non-SVM address record | `buildCreateRecordIx`, `buildVerifyRecordEthIx`, `buildVerifyRecordSvmIx`, `buildVerifyRecordBtcIx` (+ `buildRecordChallenge`, `splitEthSignature`, `splitBtcSignature`) — see [Verifying a non-SVM address record](#verifying-a-non-svm-address-record) |
+| Domain / social attestations | `buildCreateAttestationIx`, `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`) |
+| Agent records (identity, manifest, x402 hints) | `validateManifest`, `agentVerificationLevel`, `x402AcceptsFromManifest`, `agentTextRecords` — see [Agent records](#agent-records) below |
+| 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.
+
+## Agent records
+
+An `@handle` can identify, describe, and get paid as an AI agent —
+conventions on top of the existing primitives above (`HandleType.Agent`,
+text records, address records, attestations), **no new on-chain account
+family**. Full design: [`docs/agent-records.md`](../docs/agent-records.md).
+
+```ts
+import {
+  AGENT_RECORD_KEYS,
+  agentTextRecords,
+  validateManifest,
+  agentVerificationLevel,
+  x402AcceptsFromManifest,
+} from "@x1id/resolve";
+
+// after fetching + liveTextRecords(...) for the handle:
+const agent = agentTextRecords(textRecords);
+if (agent.manifest) {
+  const raw = await fetch(agent.manifest).then((r) => r.json());
+  const result = validateManifest(raw, {
+    expectedName: "payday-bot",
+    expectedHandlePda: handleAccount,
+    expectedNetwork: "testnet",
+    addressRecords: liveRecords(records), // "the chain wins" cross-check
+  });
+  if (result.ok) {
+    const level = agentVerificationLevel({
+      handleType,
+      agentRecords: agent,
+      liveAttestations: liveAttestations(attestations),
+      manifest: result.manifest,
+    }); // 0, 1, or null — L2 ("pay-to confirmed") is a live HTTP fact, not implemented here; see the MCP server
+    const hints = x402AcceptsFromManifest(result.manifest, { payTo: verifiedAddress });
+  }
+}
+```
+
+`validateManifest` never trusts a manifest's own claims over the chain: a
+`payment.addresses[]` entry claiming `verified: true` is rejected outright if
+the supplied on-chain records disagree. `agentVerificationLevel` reports only
+the highest level it actually checked — L1 requires the manifest's claimed
+attestation to match a *live* one, never assumed from presence alone.
+
+## Verifying a non-SVM address record
+
+Prove control of an ETH, BTC, or another SVM address so its `Record` gets
+`verified: true`. On-chain, the program itself recovers the address from
+the signature — this SDK never derives or checks an address client-side,
+it just builds the challenge and packages the wallet's signature.
+
+```ts
+import {
+  buildRecordChallenge,
+  buildCreateRecordIx,
+  buildVerifyRecordEthIx,
+  splitEthSignature,
+} from "@x1id/resolve";
+
+// 1. create the (unverified) record
+const createIx = buildCreateRecordIx({
+  programId, payer, owner, handle, record,
+  coinType: 60, // ETH, per SLIP-44
+  value: ethAddressBytes,
+});
+
+// 2. build the challenge and have the wallet sign it (personal_sign)
+const challenge = buildRecordChallenge("alice", 60, registeredAt, "someNonce123");
+const sig65 = await wallet.signMessage(challenge); // 65 raw bytes: r || s || v
+
+// 3. verify
+const { signature, recoveryId } = splitEthSignature(sig65);
+const verifyIx = buildVerifyRecordEthIx({
+  programId, owner, handle, record,
+  nonce: "someNonce123", signature, recoveryId,
+});
+```
+
+`buildVerifyRecordSvmIx` (the claimed address just co-signs, no challenge
+needed) and `buildVerifyRecordBtcIx` + `splitBtcSignature` (BIP-137, mainnet
+compressed-P2PKH or bech32/P2WPKH only) follow the same shape.
+
+## x402 payments
+
+An agent gets paid over HTTP via [x402](https://github.com/x402-foundation/x402)'s
+`"exact"` SVM scheme. Full design (including how transactions actually get
+built/verified — that needs real Solana parsing, so it lives in the
+[x1id MCP server](../mcp), not here): [`docs/x402.md`](../docs/x402.md).
+
+```ts
+import { buildX402Requirements, X1_TESTNET_NETWORK } from "@x1id/resolve";
+
+// server-side: one accepts[] entry for a 402 response
+const requirements = buildX402Requirements({
+  payTo: sellerAddress,
+  asset: usdcMint,
+  amount: "1000000", // smallest units, decimal string
+  buyer: buyerAddress, // x1id v1 is self-sponsored: buyer pays their own fee, no facilitator
+  memo: "invoice-42",
+});
+```
+
+This package only builds the requirements object — it does not build, sign,
+or verify a transaction (that needs `@solana/web3.js`, deliberately kept out
+of this zero-dependency package). Use the MCP server's `prepare_x402_payment`
+/ `verify_x402_payment` tools for that.
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:
@@ -240,6 +456,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;
 }
 
@@ -258,6 +475,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
@@ -289,7 +539,7 @@ attached, and this file is the accurate statement.)
 ## Links
 
 - Home & docs: **[x1id.io](https://x1id.io)**
-- Developer docs: **[docs.fortiblox.com/docs/x1id](https://docs.fortiblox.com/docs/x1id)**
+- Developer docs: **[docs.x1id.io](https://docs.x1id.io)**
 - Questions & issues: [x1id.io](https://x1id.io) — contact links in the footer
 
 ## License

package/dist/accounts.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `@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;
+    /**
+     * `Handle.records_cleared_at` (0 if never cleared) — set by `clear_records`
+     * (#8139). Every per-handle record/text-record/attestation must ALSO be
+     * judged stale when `updated_at < recordsClearedAt`, alongside (not instead
+     * of) the `registeredAt` epoch rule — see docs/record-trust.md.
+     */
+    readonly recordsClearedAt: 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,190 @@
+/**
+ * `@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;
+// `records_cleared_at` extension (`Handle::RECORDS_CLEARED_EXT_OFFSET`, #8139):
+// an i64 LE the owner bumps via `clear_records` to bulk-invalidate every
+// record/text-record/attestation without transferring the handle. Read
+// leniently — a short or zeroed account means "never cleared" (0), same
+// convention as every other Handle extension region.
+const RECORDS_CLEARED_EXT_OFFSET = 229;
+// 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;
+    const recordsClearedAt = data.length >= RECORDS_CLEARED_EXT_OFFSET + 8 ? readI64(data, RECORDS_CLEARED_EXT_OFFSET) : 0n;
+    return { name, owner, registeredAt, recordsClearedAt, 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" };
+}