@x1id/resolve 0.11.0 → 0.13.0

package/dist/index.js

@@ -35,12 +35,14 @@ export * from "./subname.js";
 export * from "./recordCount.js";
 export * from "./attestation.js";
 export * from "./gate.js";
+export * from "./gateClient.js";
 export * from "./textRecords.js";
 export * from "./lock.js";
 export * from "./integrator.js";
 export * from "./voucher.js";
 export * from "./agent.js";
 export * from "./register.js";
+export * from "./adminConfig.js";
 export * from "./lease.js";
 // Was previously imported here for internal use only, never re-exported —
 // promoted to public API 2026-09-22 because a second real package (mcp/)
@@ -57,11 +59,18 @@ export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
 export * from "./domainProof.js";
+// Named (not `export *`): `NAMESPACE_MAX_LEN` is already exported by
+// adminMarket.js, and two `export *` sharing a name would make it ambiguous
+// (dropped from the package's public surface). Re-export the scoped API, minus
+// that one equal-valued constant.
+export { scopedTldCandidate, namespaceIsActive, makeScopedHandleDeriver, } from "./scoped.js";
 import { ResolveError, CHAIN_COIN_TYPE } from "./types.js";
-import { parseName } from "./parse.js";
+import { parseName, normalizeHandle } from "./parse.js";
+import { scopedTldCandidate, namespaceIsActive, NAMESPACE_MAX_LEN, } from "./scoped.js";
 import { encodeBase58, decodeBase58_32 } from "./base58.js";
 import { DEFAULT_HANDLE_PROGRAM, TOKEN_ACCOUNT_MIN_LEN, bytesEqual, makeAccountReader, nftHolder, parseHandleAccount, readI64, readU64, } from "./accounts.js";
 import { fetchRecords, liveRecords } from "./records.js";
+import { fetchSubnames, resolveSubnameRecords } from "./subname.js";
 /** Root authority for each X1NS TLD — used to verify a fetched account really
  *  belongs to the TLD it claims. Without this check a caller handed an
  *  arbitrary account would read an owner straight out of it. */
@@ -71,6 +80,47 @@ const TLD_ROOT = Object.freeze({
     xen: "3SUwpSz33AsyJwf6B48cKZuDTswuUEdUhcXszZrFWPqo",
 });
 const SPL_NAME_HEADER_LEN = 96;
+/**
+ * Suffixes that are NEVER a subname parent: the native X1NS namespaces (handled
+ * by `parseName` before we ever reach the subname path) and the external TLDs
+ * the universal resolver owns. `foo.sol`/`foo.eth` must stay `unrecognized` to
+ * the native resolver — never resolved as a subname under `@sol`/`@eth` — so
+ * the whole never-conflate-a-namespace rule holds on the money path too.
+ */
+const SUBNAME_RESERVED_SUFFIXES = new Set([
+    "x1",
+    "xnt",
+    "xen",
+    "sol",
+    "eth",
+]);
+/**
+ * Classify `input` as a `label.parent` SUBNAME candidate by SHAPE ONLY (no
+ * chain read) — the FIRST interpretation tried for a dotted, non-`@`, non-X1NS
+ * name (owner-approved disambiguation order: subname before scoped-TLD). The
+ * shape is a single interior dot with non-empty halves, a `parent` that is not
+ * a reserved suffix, and a `label` with no further dot (a deeper `a.b.c` is
+ * sub-subname territory the one-level program does not support → stays
+ * `unrecognized`). Whether `@parent` is actually a registered handle is a chain
+ * fact the resolver establishes separately. Both halves are normalized for real
+ * at resolve; a parent that cannot be a handle (e.g. > 32 bytes) simply fails
+ * the registration check and falls through to the scoped path.
+ */
+function subnameCandidate(input) {
+    const t = input.trim().toLowerCase();
+    if (!t || t.startsWith("@"))
+        return null;
+    const dot = t.lastIndexOf(".");
+    if (dot <= 0 || dot === t.length - 1)
+        return null;
+    const label = t.slice(0, dot);
+    const parent = t.slice(dot + 1);
+    if (label.includes("."))
+        return null; // a.b.c — a true sub-subname, unsupported
+    if (SUBNAME_RESERVED_SUFFIXES.has(parent))
+        return null; // never conflate with X1NS / external
+    return { label, parent };
+}
 // `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;
@@ -91,6 +141,7 @@ export function createResolver(config) {
     // 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);
+    const scopedDeriver = config.scopedHandleDeriver ?? null;
     async function resolveX1ns(canonical, label, tld, chain, input) {
         const account = config.wasm.deriveX1nsAccount(label, tld);
         if (!account) {
@@ -178,6 +229,237 @@ export function createResolver(config) {
             : await nftHolder(reader, config.wasm, canonical, handle.nftMint, input);
         return { input, name: canonical, namespace: "handle", address, chain, verification };
     }
+    /**
+     * Resolve a SCOPED customer-TLD name `name.tld` (#8484/#8485), or throw
+     * `unrecognized` when `.tld` is not one of OUR launched namespaces — so an
+     * unlaunched `.tld` behaves exactly as before (never a scoped hit). The
+     * contract mirrors `tools/api`'s `resolve_scoped`: canonicalize both halves
+     * as the program does, confirm `["namespace", tld]` is a program-owned Active
+     * `Namespace`, then derive `["handle", tld, name]` and read its CURRENT
+     * authority through the SAME owner/tokenization/record path a bare `@handle`
+     * uses — only the `name`/`namespace` fields differ (the TLD label).
+     */
+    async function resolveScoped(subRaw, tldRaw, chain, input) {
+        // The exact fall-through the native parser would have produced: a
+        // non-canonical half, or a `.tld` that is not a launched namespace, is
+        // simply "not a handle or a known domain" — never a misleading
+        // invalid-handle, and never a scoped hit on a name we do not own.
+        const notScoped = () => new ResolveError("unrecognized", `"${input.trim()}" is not a handle or a known domain`, input);
+        // Canonicalize both halves exactly as the program's `handle_normalize`
+        // does. A half that does not normalize can never name one of our scoped
+        // names — fall through rather than erroring (matches resolve_scoped).
+        let name;
+        let label;
+        try {
+            name = normalizeHandle(subRaw);
+            label = normalizeHandle(tldRaw);
+        }
+        catch {
+            throw notScoped();
+        }
+        if (label.length > NAMESPACE_MAX_LEN)
+            throw notScoped();
+        if (ttl > 0) {
+            const hit = cache.get(`scoped:${label}:${name}:${chain}`);
+            if (hit && hit.expires > Date.now())
+                return hit.value;
+        }
+        // Is `.label` a launched, Active X1ID namespace? Derive `["namespace",
+        // label]` via the WASM (canonical, always available) and read it. It must
+        // exist, be owned by the registry program, and carry `status == Active`.
+        const nsAccountKey = config.wasm.deriveNamespaceAccount(label, handleProgram);
+        if (!nsAccountKey)
+            throw notScoped();
+        const ns = await accountInfo(encodeBase58(nsAccountKey));
+        if (!ns || ns.owner !== programBase58 || !namespaceIsActive(ns.data)) {
+            // Not one of our launched namespaces — preserve today's behavior so an
+            // unlaunched `.tld` (and `.sol`/`.eth`, handled elsewhere) stays
+            // "unrecognized", never resolved through the wrong path.
+            throw notScoped();
+        }
+        // Confirmed a scoped X1ID name. From here any failure is a REAL error,
+        // never a silent fall-through (mirrors resolve_scoped's comment).
+        if (!scopedDeriver) {
+            throw new ResolveError("not-configured", `.${label} is a launched X1ID TLD, but scoped resolution needs a PDA deriver — install @solana/web3.js and pass scopedHandleDeriver (see makeScopedHandleDeriver)`, input);
+        }
+        // `makeScopedHandleDeriver(web3)` is async; a common footgun is passing the
+        // un-awaited Promise as `scopedHandleDeriver`, which would otherwise surface
+        // a baffling `scopedDeriver.scopedHandleKey is not a function` wrapped as an
+        // rpc-error. Detect the Promise/thenable (or any object missing the method)
+        // and fail with an actionable message instead.
+        if (typeof scopedDeriver.then === "function" ||
+            typeof scopedDeriver.scopedHandleKey !== "function") {
+            throw new ResolveError("not-configured", "scopedHandleDeriver must be the awaited result of makeScopedHandleDeriver(web3), not the Promise it returns — did you forget `await`?", input);
+        }
+        let pda;
+        try {
+            pda = await scopedDeriver.scopedHandleKey(label, name, programBase58);
+        }
+        catch (e) {
+            throw new ResolveError("rpc-error", `scoped handle derivation failed: ${String(e)}`, input);
+        }
+        const h = await accountInfo(pda);
+        // An account at the PDA the registry does not own is not a handle — the
+        // scoped name is unregistered under this (live) TLD.
+        if (!h || h.owner !== programBase58) {
+            throw new ResolveError("not-found", `${name}.${label} is not registered`, input);
+        }
+        const handle = parseHandleAccount(h.data);
+        if (!handle) {
+            throw new ResolveError("rpc-error", `${name}.${label} returned a malformed account`, input);
+        }
+        const display = `${name}.${label}`;
+        let value;
+        if (chain !== "X1" && chain !== "SOL") {
+            // ETH/BTC addresses live in per-chain `Record` accounts — same staleness
+            // rule as a bare handle (fetchRecords → liveRecords).
+            const live = liveRecords(await fetchRecords(rpc, programBase58, pda, handle.registeredAt, handle.recordsClearedAt));
+            const record = live.find((r) => r.coinType === CHAIN_COIN_TYPE[chain]);
+            if (!record) {
+                throw new ResolveError("no-record-for-chain", `${display} has no ${chain} record`, input);
+            }
+            value = {
+                input,
+                name: display,
+                namespace: label,
+                address: record.address,
+                chain,
+                verification: record.verified ? "verified" : "unverified",
+            };
+        }
+        else {
+            // Same authority rule as a bare handle: untokenized → `Handle.owner`
+            // (verified); tokenized → whoever holds the NFT now (verified only in its
+            // ATA). A scoped name is always tokenized in practice, but both branches
+            // are kept so the shape is byte-identical to resolveHandle.
+            const { address, verification } = handle.nftMint === null
+                ? { address: encodeBase58(handle.owner), verification: "verified" }
+                : await nftHolder(reader, config.wasm, display, handle.nftMint, input);
+            value = { input, name: display, namespace: label, address, chain, verification };
+        }
+        if (ttl > 0)
+            cache.set(`scoped:${label}:${name}:${chain}`, { value, expires: Date.now() + ttl });
+        return value;
+    }
+    /**
+     * Resolve a `label.parent` SUBNAME (#7375) — a label under a parent
+     * `@handle`, e.g. `pay.alice`. Called ONLY for a dotted, non-`@`, non-X1NS
+     * input (the native parser's `unrecognized` fall-through), and BEFORE the
+     * scoped customer-TLD path, per the owner-approved disambiguation order.
+     *
+     * Returns `null` — the signal to try the scoped path next — when `@parent`
+     * is NOT a registered handle (so `x.y` was never a subname). Once `@parent`
+     * IS a registered handle we are COMMITTED to the subname interpretation:
+     * every outcome is a `Resolved` or a throw (`not-found` / `no-record-for-chain`),
+     * never a fall-through to scoped.
+     *
+     * A subname has NO owner; it resolves PURELY through its per-chain `Record`s
+     * (like an ETH/BTC record on a handle), so EVERY chain — X1/SOL included —
+     * comes from a record, never an owner key. Both staleness layers of
+     * docs/record-trust.md are enforced via `subname.ts`:
+     *   1. `subname.createdAt >= parent.registeredAt` — else the subname was left
+     *      behind by a PREVIOUS owner of the parent (any transfer/sale/recovery/
+     *      re-registration bumps `registered_at`): `not-found`, never resolved.
+     *   2. `record.updatedAt >= subname.createdAt` — a record from a previous
+     *      incarnation of the same `["subname", parent, label]` PDA is dropped.
+     * The subname account itself is located by the program-scoped
+     * `getProgramAccounts` scan (`fetchSubnames`) — scoping the scan to the
+     * registry program id IS the ownership check — then matched by canonical
+     * label; nothing is hand-derived here (the WASM module has no subname PDA
+     * derivation and this package never hand-rolls the on-curve check).
+     */
+    async function resolveSubname(labelRaw, parentRaw, chain, input) {
+        // The parent half must canonicalize as a handle; if it cannot, `@parent`
+        // can never be a registered handle → not a subname, try scoped instead.
+        let parentCanonical;
+        try {
+            parentCanonical = normalizeHandle(parentRaw);
+        }
+        catch {
+            return null;
+        }
+        // The subname label must also canonicalize as a handle label (same rules).
+        // If it cannot we cannot build a cache key yet — defer the verdict until
+        // after the parent-registration check decides the branch.
+        let subLabel = null;
+        try {
+            subLabel = normalizeHandle(labelRaw);
+        }
+        catch {
+            subLabel = null;
+        }
+        if (subLabel !== null && ttl > 0) {
+            const hit = cache.get(`subname:${parentCanonical}:${subLabel}:${chain}`);
+            if (hit && hit.expires > Date.now())
+                return hit.value;
+        }
+        // Is `@parent` a REGISTERED handle? That — and only that — decides whether
+        // `x.y` is a subname. `not-found`/`invalid-handle` → not a subname, fall
+        // through to scoped; a real rpc-error/malformed account propagates.
+        let parent;
+        try {
+            parent = await fetchHandle(parentCanonical, input);
+        }
+        catch (e) {
+            if (e instanceof ResolveError && (e.code === "not-found" || e.code === "invalid-handle")) {
+                return null;
+            }
+            throw e;
+        }
+        // COMMITTED to the subname interpretation: `@parent` is a live handle.
+        if (subLabel === null) {
+            throw new ResolveError("not-found", `"${input.trim()}" is not a subname of @${parentCanonical}`, input);
+        }
+        const display = `${subLabel}.${parentCanonical}`;
+        // Locate the subname account via the program scan (ownership check), then
+        // match the canonical label. `fetchSubnames` already flags each with
+        // `live` (staleness layer 1: createdAt >= parent.registeredAt).
+        const subs = await fetchSubnames(rpc, programBase58, parent.pda, parent.handle.registeredAt);
+        const match = subs.find((s) => s.label === subLabel);
+        if (!match) {
+            throw new ResolveError("not-found", `${display} is not a subname of @${parentCanonical}`, input);
+        }
+        // Staleness layer 1 — a subname stranded by a parent transfer/re-registration
+        // belongs to a PREVIOUS owner and must NEVER resolve to a payment address.
+        if (!match.live) {
+            throw new ResolveError("not-found", `${display} was created before the current @${parentCanonical} registration — it belongs to a previous owner`, input);
+        }
+        // Read the subname's LIVE records. `resolveSubnameRecords` re-applies layer
+        // 1 (returns [] when stale) AND layer 2 (record.updatedAt >= createdAt),
+        // dropping any stale record — the only safe entry point.
+        const subname = {
+            parent: match.parent,
+            label: match.label,
+            createdAt: match.createdAt,
+            bump: match.bump,
+        };
+        const records = await resolveSubnameRecords(rpc, programBase58, match.account, subname, parent.handle.registeredAt);
+        const record = records.find((r) => !r.stale && r.coinType === CHAIN_COIN_TYPE[chain]);
+        if (!record) {
+            throw new ResolveError("no-record-for-chain", `${display} has no ${chain} record`, input);
+        }
+        const value = {
+            input,
+            name: display,
+            // A subname is its own namespace — never "handle" (so a consumer that
+            // branches on `=== "handle"`, e.g. dev-api's attestation enrichment, does
+            // not treat it as a top-level handle) and never the parent's.
+            namespace: "subname",
+            address: record.address,
+            chain,
+            // Like a handle's ETH/BTC record: `unverified` unless the record itself
+            // is co-signed/verified (and `verified` is already forced false for any
+            // stale record by records.ts).
+            verification: record.verified ? "verified" : "unverified",
+        };
+        if (ttl > 0) {
+            cache.set(`subname:${parentCanonical}:${subLabel}:${chain}`, {
+                value,
+                expires: Date.now() + ttl,
+            });
+        }
+        return value;
+    }
     /** See `Resolver.records`. */
     async function records(input) {
         const parsed = parseName(input); // throws with a specific code
@@ -189,7 +471,34 @@ export function createResolver(config) {
     }
     async function resolve(input, opts) {
         const chain = opts?.chain ?? "X1";
-        const parsed = parseName(input); // throws with a specific code
+        let parsed;
+        try {
+            parsed = parseName(input); // throws with a specific code
+        }
+        catch (e) {
+            // A dotted, non-`@`, non-X1NS name is `unrecognized` to the strict native
+            // parser — but it MAY be a SUBNAME `label.parent` (#7375) or a scoped
+            // customer-TLD name `name.tld` (#8484/#8485). Owner-approved
+            // disambiguation order: try the subname interpretation FIRST (when
+            // `@parent` is a registered handle), then the scoped path. Each re-throws
+            // / falls through so `.sol`/`.eth`/unknown TLDs behave exactly as before.
+            // Any other code (ambiguous / invalid-*) is preserved verbatim.
+            if (e instanceof ResolveError && e.code === "unrecognized") {
+                const sub = subnameCandidate(input);
+                if (sub) {
+                    // `null` ⇒ `@parent` is not a registered handle ⇒ not a subname;
+                    // fall through to the scoped path. A committed subname path either
+                    // returns a `Resolved` or throws (never reaches scoped).
+                    const resolved = await resolveSubname(sub.label, sub.parent, chain, input);
+                    if (resolved !== null)
+                        return resolved;
+                }
+                const cand = scopedTldCandidate(input);
+                if (cand)
+                    return resolveScoped(cand.sub, cand.tld, chain, input);
+            }
+            throw e;
+        }
         const key = `${parsed.namespace}:${parsed.canonical}:${chain}`;
         if (ttl > 0) {
             const hit = cache.get(key);
@@ -273,8 +582,15 @@ export function createResolver(config) {
      */
     async function reverse(address) {
         const owner = decodeBase58_32(address);
-        if (!owner)
-            throw new ResolveError("unrecognized", `"${address}" is not an address`, address);
+        // `decodeBase58_32` left-pads a short/tiny base58 input into 32 bytes, so a
+        // malformed address like "abc" would otherwise slip through as a valid tiny
+        // key. Require the canonical round-trip: a malformed address must THROW
+        // (matching the dev-api's 400 INVALID_ADDRESS and the docs/drill checklist),
+        // reserving the `null` return exclusively for a WELL-FORMED address that
+        // genuinely has no primary.
+        if (!owner || encodeBase58(owner) !== address) {
+            throw new ResolveError("unrecognized", `"${address}" is not a valid X1 address`, address);
+        }
         const handleName = await reverseHandle(owner);
         if (handleName !== null)
             return handleName;
@@ -304,3 +620,9 @@ export function createResolver(config) {
         clearCache: () => cache.clear(),
     };
 }
+export * from "./adminMarket.js";
+export * from "./namespaceOverride.js";
+// The X1ID Universal Resolver (#8475): cross-namespace resolution (.sol via SNS,
+// .eth via ENS) alongside the native path. Additive — the native resolver above
+// is untouched; `createUniversalResolver` composes it with external adapters.
+export * from "./universal.js";

package/dist/namespaceOverride.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Per-handle namespace overrides — `create_namespace_override` /
+ * `update_namespace_override` / `close_namespace_override` (#8138 family).
+ *
+ * A namespace override lets a handle's owner redirect `<handle>.<namespace>`
+ * (e.g. `jack.xnt`) to a DIFFERENT address than the handle's default, per
+ * namespace label. It is a record-edit-authority action (the handle owner, or a
+ * record delegate, signs — NOT an admin action), in the same family as the
+ * address `Record` writers: an optional `record_delegate` named slot plus the
+ * tokenized-handle holder-ATA proof in `remaining_accounts[0]`.
+ *
+ * NOTE: this capability is built but NOT yet wired into public resolution —
+ * `resolve()` does not read overrides yet (that is the cutover switch). These
+ * builders + the decoder are the on-chain-write + read-decode half, ready for
+ * when namespaced resolution goes live.
+ *
+ * Hand-rolled like the rest of the package — no Anchor client, no web3.js. PDAs
+ * are not derived here: derive `["handle", name]`, `["namespace", label]`,
+ * `["namespace_override", handlePubkey, label]`, `["delegate", handlePubkey]`
+ * with your runtime and pass them in, same convention as records.ts / subname.ts.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+/** sha256("global:create_namespace_override")[..8]. */
+export declare const CREATE_NAMESPACE_OVERRIDE_DISCRIMINATOR: Uint8Array;
+/** sha256("global:update_namespace_override")[..8]. */
+export declare const UPDATE_NAMESPACE_OVERRIDE_DISCRIMINATOR: Uint8Array;
+/** sha256("global:close_namespace_override")[..8]. */
+export declare const CLOSE_NAMESPACE_OVERRIDE_DISCRIMINATOR: Uint8Array;
+/** The Anchor ACCOUNT discriminator for a `NamespaceOverride` — sha256("account:NamespaceOverride")[..8]. */
+export declare const NAMESPACE_OVERRIDE_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** The record-edit-authority tail every writer here shares: an optional named
+ *  `record_delegate` slot (None = the program-id placeholder), then the
+ *  tokenized-handle holder-ATA proof in remaining_accounts[0]. Own copy per
+ *  module, matching recordWrite.ts's convention. */
+interface AuthorityTail {
+    /** `["delegate", handle]` PDA — pass when a record delegate (not the owner) signs. */
+    readonly recordDelegate?: AddressLike;
+    /** The owner's pNFT token account — REQUIRED for a tokenized handle (proves
+     *  the signer holds the capability NFT); omit for an untokenized handle. */
+    readonly holderTokenAccount?: AddressLike;
+}
+export interface CreateNamespaceOverrideParams extends AuthorityTail {
+    readonly programId: AddressLike;
+    /** Rent payer for the new override account; signs. */
+    readonly payer: AddressLike;
+    /** The handle owner (or delegate signer); signs. */
+    readonly owner: AddressLike;
+    /** `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** `["namespace", label]` PDA — must be Active for a create. */
+    readonly namespace: AddressLike;
+    /** `["namespace_override", handle, label]` PDA (init). */
+    readonly namespaceOverride: AddressLike;
+    /** The namespace label (e.g. "xnt"), an instruction ARG (== the seed). */
+    readonly namespaceLabel: string;
+    /** The address `<handle>.<label>` should resolve to. */
+    readonly value: AddressLike;
+}
+/** Build `create_namespace_override`. Args: namespace_label (String) + value (Pubkey). */
+export declare function buildCreateNamespaceOverrideIx(p: CreateNamespaceOverrideParams): BuiltInstruction;
+export interface UpdateNamespaceOverrideParams extends AuthorityTail {
+    readonly programId: AddressLike;
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    /** `["namespace_override", handle, label]` PDA (self-seeds from its stored label). */
+    readonly namespaceOverride: AddressLike;
+    /** The new target address. */
+    readonly value: AddressLike;
+}
+/** Build `update_namespace_override` — change the target address. Arg: value (Pubkey). */
+export declare function buildUpdateNamespaceOverrideIx(p: UpdateNamespaceOverrideParams): BuiltInstruction;
+export interface CloseNamespaceOverrideParams extends AuthorityTail {
+    readonly programId: AddressLike;
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    /** `["namespace_override", handle, label]` PDA (closed to recipient). */
+    readonly namespaceOverride: AddressLike;
+    /** Lamports recipient for the closed override's rent; need not sign. */
+    readonly recipient: AddressLike;
+}
+/** Build `close_namespace_override` — close the override, rent to recipient. No args. */
+export declare function buildCloseNamespaceOverrideIx(p: CloseNamespaceOverrideParams): BuiltInstruction;
+export interface NamespaceOverride {
+    /** The handle PDA this override belongs to. */
+    readonly handle: string;
+    /** The namespace label it applies to (e.g. "xnt"). */
+    readonly namespace: string;
+    /** The address `<handle>.<namespace>` resolves to instead of the default. */
+    readonly value: string;
+    /** Unix seconds last stamped. Trust ONLY while `updatedAt >= handle.registeredAt`
+     *  (the universal epoch-staleness rule — a release+re-register reuses the PDA). */
+    readonly updatedAt: bigint;
+    readonly bump: number;
+}
+/** Decode a `NamespaceOverride` account. Layout: disc(8) | handle(32) |
+ *  namespace(String: u32 len + bytes) | value(32) | updated_at(i64) | bump(1).
+ *  Returns null if the data is too short / malformed. */
+export declare function decodeNamespaceOverride(data: Uint8Array): NamespaceOverride | null;
+/**
+ * Fetch + decode a handle's namespace override for one label, applying the
+ * universal epoch-staleness rule — a `NamespaceOverride` PDA is reused across a
+ * release + re-register of the same handle, so an override from a PREVIOUS owner
+ * (stamped before `handleRegisteredAt`) must NOT count. Returns the live
+ * override, or null when there is none / it is stale / the account is malformed.
+ *
+ * GATED read path: this is NOT called by `resolve()` — namespaced resolution does
+ * not honor overrides yet (that is the cutover switch). Derive `overrideAccount`
+ * with `WasmResolver.deriveNamespaceOverrideAccount(handle, label, programId)`.
+ */
+export declare function fetchNamespaceOverride(rpc: RpcFn, overrideAccount: string, handleRegisteredAt: bigint): Promise<NamespaceOverride | null>;
+/**
+ * List all LIVE namespace overrides for one handle (a getProgramAccounts scan
+ * filtered by the account discriminator + the `handle` field at offset 8), with
+ * the epoch-staleness rule applied. Each entry includes its account address.
+ *
+ * GATED read path — not used by `resolve()` yet. Pass the handle's
+ * `registeredAt` so previous-owner overrides are dropped.
+ */
+export declare function fetchNamespaceOverridesForHandle(rpc: RpcFn, programId: string, handleAccount: string, handleRegisteredAt: bigint): Promise<Array<NamespaceOverride & {
+    account: string;
+}>>;
+export {};