@x1id/resolve 0.11.0 → 0.12.0

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 {};

package/dist/namespaceOverride.js

@@ -0,0 +1,204 @@
+/**
+ * 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 { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { recordDelegateNonePlaceholder, recordDelegateSomeSlot } from "./delegate.js";
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+/** sha256("global:create_namespace_override")[..8]. */
+export const CREATE_NAMESPACE_OVERRIDE_DISCRIMINATOR = Uint8Array.from([86, 74, 181, 245, 1, 190, 77, 128]);
+/** sha256("global:update_namespace_override")[..8]. */
+export const UPDATE_NAMESPACE_OVERRIDE_DISCRIMINATOR = Uint8Array.from([6, 194, 181, 7, 155, 17, 115, 224]);
+/** sha256("global:close_namespace_override")[..8]. */
+export const CLOSE_NAMESPACE_OVERRIDE_DISCRIMINATOR = Uint8Array.from([95, 135, 159, 93, 70, 49, 213, 188]);
+/** The Anchor ACCOUNT discriminator for a `NamespaceOverride` — sha256("account:NamespaceOverride")[..8]. */
+export const NAMESPACE_OVERRIDE_ACCOUNT_DISCRIMINATOR = Uint8Array.from([53, 237, 118, 139, 3, 149, 13, 148]);
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+function encString(s) {
+    const bytes = new TextEncoder().encode(s);
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+function concat(parts) {
+    const len = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(len);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function pushAuthorityTail(keys, programId, p) {
+    if (p.recordDelegate !== undefined) {
+        keys.push(recordDelegateSomeSlot(p.recordDelegate));
+    }
+    else if (p.holderTokenAccount !== undefined) {
+        keys.push(recordDelegateNonePlaceholder(programId));
+    }
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+}
+/** Build `create_namespace_override`. Args: namespace_label (String) + value (Pubkey). */
+export function buildCreateNamespaceOverrideIx(p) {
+    const data = concat([CREATE_NAMESPACE_OVERRIDE_DISCRIMINATOR, encString(p.namespaceLabel), toBytes32(p.value, "value")]);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.namespace, "namespace"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.namespaceOverride, "namespaceOverride"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `update_namespace_override` — change the target address. Arg: value (Pubkey). */
+export function buildUpdateNamespaceOverrideIx(p) {
+    const data = concat([UPDATE_NAMESPACE_OVERRIDE_DISCRIMINATOR, toBytes32(p.value, "value")]);
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.namespaceOverride, "namespaceOverride"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `close_namespace_override` — close the override, rent to recipient. No args. */
+export function buildCloseNamespaceOverrideIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.namespaceOverride, "namespaceOverride"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data: CLOSE_NAMESPACE_OVERRIDE_DISCRIMINATOR.slice() };
+}
+/** 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 function decodeNamespaceOverride(data) {
+    if (data.length < 8 + 32 + 4)
+        return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const handle = encodeBase58(data.subarray(8, 40));
+    const labelLen = dv.getUint32(40, true);
+    const labelStart = 44;
+    const labelEnd = labelStart + labelLen;
+    const valueEnd = labelEnd + 32;
+    const updatedEnd = valueEnd + 8;
+    if (data.length < updatedEnd + 1)
+        return null;
+    let namespace;
+    try {
+        namespace = new TextDecoder().decode(data.subarray(labelStart, labelEnd));
+    }
+    catch {
+        return null;
+    }
+    const value = encodeBase58(data.subarray(labelEnd, valueEnd));
+    const updatedAt = dv.getBigInt64(valueEnd, true);
+    const bump = data[updatedEnd];
+    return { handle, namespace, value, updatedAt, bump };
+}
+/**
+ * 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 async function fetchNamespaceOverride(rpc, overrideAccount, handleRegisteredAt) {
+    const res = (await rpc("getAccountInfo", [
+        overrideAccount,
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const data0 = res?.value?.data?.[0];
+    if (!data0)
+        return null;
+    const bin = atob(data0);
+    const raw = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        raw[i] = bin.charCodeAt(i);
+    const decoded = decodeNamespaceOverride(raw);
+    if (!decoded)
+        return null;
+    // Epoch-staleness: ignore an override left by a previous owner.
+    if (decoded.updatedAt < handleRegisteredAt)
+        return null;
+    return decoded;
+}
+/**
+ * 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 async function fetchNamespaceOverridesForHandle(rpc, programId, handleAccount, handleRegisteredAt) {
+    const res = (await rpc("getProgramAccounts", [
+        programId,
+        {
+            encoding: "base64",
+            commitment: "confirmed",
+            filters: [
+                { memcmp: { offset: 0, bytes: encodeBase58(NAMESPACE_OVERRIDE_ACCOUNT_DISCRIMINATOR) } },
+                { memcmp: { offset: 8, bytes: handleAccount } },
+            ],
+        },
+    ]));
+    const out = [];
+    for (const a of res ?? []) {
+        const bin = atob(a.account.data[0]);
+        const raw = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            raw[i] = bin.charCodeAt(i);
+        const decoded = decodeNamespaceOverride(raw);
+        // Defence in depth + staleness: the memcmp should guarantee the handle, but
+        // skip a mismatch or a previous-owner override.
+        if (decoded && decoded.handle === handleAccount && decoded.updatedAt >= handleRegisteredAt) {
+            out.push({ ...decoded, account: a.pubkey });
+        }
+    }
+    out.sort((x, y) => x.namespace.localeCompare(y.namespace));
+    return out;
+}

package/dist/register.d.ts

@@ -58,6 +58,36 @@ export interface RegisterParams {
  * payer a price before they sign.
  */
 export declare function buildRegisterIx(p: RegisterParams): BuiltInstruction;
+/** Anchor instruction discriminator: `sha256("global:register_reserved")[0..8]`. */
+export declare const REGISTER_RESERVED_DISCRIMINATOR: Uint8Array;
+export interface RegisterReservedParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** `Config.admin` — the ONLY key this instruction accepts (the program's
+     *  `has_one = admin` constraint). Signs AND pays the new `Handle` account's
+     *  rent. On x1id today admin == treasury == the deploy key. */
+    readonly admin: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The `["handle", name]` PDA being claimed — must not already exist
+     *  (`init`). On success the handle's owner is set to `Config.treasury`. */
+    readonly handle: AddressLike;
+    /** Canonical form (`parseName(...).canonical`), MIN_LEN..=32 bytes. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+}
+/**
+ * Build `register_reserved` — the admin-only, free registration of a reserved
+ * name INTO THE TREASURY (owner is set on-chain to `Config.treasury`, not to an
+ * arbitrary target). Admin-gated: the `admin` account must equal `Config.admin`
+ * and must sign. No price, no treasury-payment account — reserved registration
+ * is free; the admin just pays the new account's rent.
+ *
+ * Same hand-rolled shape as {@link buildRegisterIx}. Returns unsigned
+ * instruction data for the caller's runtime to assemble, sign (with the admin
+ * key) and submit.
+ */
+export declare function buildRegisterReservedIx(p: RegisterReservedParams): BuiltInstruction;
 /** The `Config` fields `register_with_forti` needs beyond what
  *  {@link fetchConfigTreasury} already reads. `fortiRatePerLamport === 0n`
  *  means FORTI payment is not enabled on this deployment — the same

package/dist/register.js

@@ -103,6 +103,43 @@ export function buildRegisterIx(p) {
     }
     return { programId: toBase58(p.programId, "programId"), keys, data };
 }
+// ============================= register_reserved (#8404) =============================
+/** Anchor instruction discriminator: `sha256("global:register_reserved")[0..8]`. */
+export const REGISTER_RESERVED_DISCRIMINATOR = Uint8Array.from([
+    37, 151, 239, 242, 251, 26, 205, 224,
+]);
+/**
+ * Build `register_reserved` — the admin-only, free registration of a reserved
+ * name INTO THE TREASURY (owner is set on-chain to `Config.treasury`, not to an
+ * arbitrary target). Admin-gated: the `admin` account must equal `Config.admin`
+ * and must sign. No price, no treasury-payment account — reserved registration
+ * is free; the admin just pays the new account's rent.
+ *
+ * Same hand-rolled shape as {@link buildRegisterIx}. Returns unsigned
+ * instruction data for the caller's runtime to assemble, sign (with the admin
+ * key) and submit.
+ */
+export function buildRegisterReservedIx(p) {
+    if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+    const nameBytes = new TextEncoder().encode(p.name);
+    if (nameBytes.length < 1 || nameBytes.length > 32) {
+        throw new Error("name must be 1..=32 bytes (UTF-8)");
+    }
+    const data = new Uint8Array(8 + 4 + nameBytes.length + 1);
+    data.set(REGISTER_RESERVED_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nameBytes.length, true);
+    data.set(nameBytes, 12);
+    data[12 + nameBytes.length] = p.handleType;
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
 // ============================= register_with_forti (#8136, WP #8200) =============================
 /** Byte offsets of the `Config` fields `register_with_forti` needs, verbatim
  *  from state.rs's field order (confirmed against `migrate_config_v4`'s own

package/dist/scoped.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Scoped customer-TLD names (`alices.testtld`) — the SDK last-mile of the
+ * namespace-registrar feature (#8484/#8485).
+ *
+ * A launched X1ID namespace `.tld` is a program-owned `Namespace` account at
+ * `["namespace", tld]` with `status == Active`. A name registered under it is a
+ * (always-tokenized) `Handle` at the TWO-SEED-plus-prefix PDA
+ * `["handle", tld, name]` — a DIFFERENT account from the bare `@name`'s
+ * `["handle", name]`, so `alices.testtld` and `@alices` can have different
+ * owners. This module is the shape classifier, the `Namespace` status reader and
+ * the injected PDA deriver the resolver uses to answer a scoped name; the
+ * owner/tokenization/verification read reuses the bare-handle authority path
+ * verbatim (see `createResolver` in index.ts).
+ *
+ * The resolution CONTRACT is `tools/api`'s `resolve_scoped` (Rust, the
+ * authority): canonicalize both halves exactly as the program does, confirm
+ * `.tld` is a launched Active namespace, then derive `["handle", tld, name]` and
+ * resolve its current authority — with `namespace` set to the TLD label.
+ *
+ * # Why the deriver is injected (not hand-rolled, not WASM)
+ *
+ * The WASM module exposes `["namespace", label]` (`deriveNamespaceAccount`) but
+ * NO two-seed scoped-handle derivation, and this package's one rule is to never
+ * hand-roll `find_program_address`'s ed25519 on-curve check in TypeScript (see
+ * wasm.ts). So `["handle", tld, name]` is derived through an INJECTED
+ * {@link ScopedHandleDeriver} — exactly the pattern the SNS adapter uses for its
+ * `.sol` name-account PDA. Build the default with {@link makeScopedHandleDeriver}
+ * (which uses `@solana/web3.js`), or inject your own (a test fake, or a runtime
+ * that already owns a `findProgramAddress`).
+ */
+/** Max byte length of a TLD label (`NAMESPACE_MAX_LEN`, the program's state.rs). */
+export declare const NAMESPACE_MAX_LEN = 16;
+/** A `name.tld` split, when `input` is SHAPED like a scoped customer-TLD name. */
+export interface ScopedCandidate {
+    /** The sub-name half (`"alices"`), lowercased; validated for real at resolve. */
+    readonly sub: string;
+    /** The TLD-label half (`"testtld"`), lowercased and label-charset-checked. */
+    readonly tld: string;
+}
+/**
+ * Classify `input` as a scoped customer-TLD candidate by SHAPE ONLY — no chain
+ * read. Returns the split, or null when the input is not that shape.
+ *
+ * The shape is a single interior dot with non-empty halves, no leading `@`, and
+ * a `tld` that is a plausible namespace label (the program's charset + the
+ * 1..=`NAMESPACE_MAX_LEN` length rule) and is NOT one of the reserved suffixes.
+ * Whether `.tld` is actually a launched namespace is a chain fact the resolver
+ * establishes separately — this only decides whether it is worth asking.
+ * Mirrors `app/src/lib/x1/namespaceRegister.ts`'s `namespaceSublabelShape` and
+ * the shape gate in `tools/api`'s `resolve`.
+ */
+export declare function scopedTldCandidate(input: string): ScopedCandidate | null;
+/**
+ * Whether a raw `Namespace` account's bytes say it is `Active`, byte-for-byte
+ * the authority's `namespace_active_from_bytes` (tools/api). Layout: disc(8) |
+ * label(Borsh `String`: u32 LE length + UTF-8 bytes) | status(u8), and
+ * `NamespaceStatus::Active` is the first enum variant (Borsh tag 0). Only the
+ * length prefix and the one status byte are parsed — nothing past it. `false`
+ * for any buffer too short to hold disc + length prefix + the status byte (a
+ * malformed/wrong account is never read as Active). The CALLER must also check
+ * the account is owned by the registry program — this reads bytes only.
+ */
+export declare function namespaceIsActive(data: Uint8Array): boolean;
+/**
+ * The one `find_program_address` derivation scoped resolution needs: the
+ * two-seed-plus-prefix scoped handle PDA `["handle", tld, name]`. Injected so
+ * the SDK core stays free of curve math (and of a hard `@solana/web3.js`
+ * dependency), and so tests can supply a deterministic fake.
+ */
+export interface ScopedHandleDeriver {
+    /** The `["handle", label, name]` PDA under `programId`, base58. */
+    scopedHandleKey(label: string, name: string, programId: string): Promise<string> | string;
+}
+/**
+ * Build the default scoped-handle deriver using `@solana/web3.js`.
+ *
+ * Seeds are `["handle", label, name]` under the registry program — exactly the
+ * order `tools/api`'s `scoped_handle_pda` and the program's
+ * `register_under_namespace` use, so the derived PDA is the account the name
+ * actually lives at. Prefers an INJECTED web3 module (robust under `file:` /
+ * `npm link`, where a bare specifier resolves from THIS package's realpath, not
+ * the consumer's); falls back to a dynamic import for a normal install.
+ */
+export declare function makeScopedHandleDeriver(web3Module?: unknown): Promise<ScopedHandleDeriver>;

package/dist/scoped.js

@@ -0,0 +1,126 @@
+/**
+ * Scoped customer-TLD names (`alices.testtld`) — the SDK last-mile of the
+ * namespace-registrar feature (#8484/#8485).
+ *
+ * A launched X1ID namespace `.tld` is a program-owned `Namespace` account at
+ * `["namespace", tld]` with `status == Active`. A name registered under it is a
+ * (always-tokenized) `Handle` at the TWO-SEED-plus-prefix PDA
+ * `["handle", tld, name]` — a DIFFERENT account from the bare `@name`'s
+ * `["handle", name]`, so `alices.testtld` and `@alices` can have different
+ * owners. This module is the shape classifier, the `Namespace` status reader and
+ * the injected PDA deriver the resolver uses to answer a scoped name; the
+ * owner/tokenization/verification read reuses the bare-handle authority path
+ * verbatim (see `createResolver` in index.ts).
+ *
+ * The resolution CONTRACT is `tools/api`'s `resolve_scoped` (Rust, the
+ * authority): canonicalize both halves exactly as the program does, confirm
+ * `.tld` is a launched Active namespace, then derive `["handle", tld, name]` and
+ * resolve its current authority — with `namespace` set to the TLD label.
+ *
+ * # Why the deriver is injected (not hand-rolled, not WASM)
+ *
+ * The WASM module exposes `["namespace", label]` (`deriveNamespaceAccount`) but
+ * NO two-seed scoped-handle derivation, and this package's one rule is to never
+ * hand-roll `find_program_address`'s ed25519 on-curve check in TypeScript (see
+ * wasm.ts). So `["handle", tld, name]` is derived through an INJECTED
+ * {@link ScopedHandleDeriver} — exactly the pattern the SNS adapter uses for its
+ * `.sol` name-account PDA. Build the default with {@link makeScopedHandleDeriver}
+ * (which uses `@solana/web3.js`), or inject your own (a test fake, or a runtime
+ * that already owns a `findProgramAddress`).
+ */
+import { ResolveError } from "./types.js";
+/** Max byte length of a TLD label (`NAMESPACE_MAX_LEN`, the program's state.rs). */
+export const NAMESPACE_MAX_LEN = 16;
+/** The suffixes that are NEVER a scoped X1ID TLD: the native X1NS namespaces
+ *  and the external ones the universal resolver owns. A scoped candidate whose
+ *  suffix is one of these is refused here so `.x1`/`.xnt`/`.xen` stay on the
+ *  X1NS path and `.sol`/`.eth` stay with their own adapters — the whole
+ *  never-conflate-a-namespace rule. */
+const RESERVED_SUFFIXES = new Set(["x1", "xnt", "xen", "sol", "eth"]);
+/**
+ * Classify `input` as a scoped customer-TLD candidate by SHAPE ONLY — no chain
+ * read. Returns the split, or null when the input is not that shape.
+ *
+ * The shape is a single interior dot with non-empty halves, no leading `@`, and
+ * a `tld` that is a plausible namespace label (the program's charset + the
+ * 1..=`NAMESPACE_MAX_LEN` length rule) and is NOT one of the reserved suffixes.
+ * Whether `.tld` is actually a launched namespace is a chain fact the resolver
+ * establishes separately — this only decides whether it is worth asking.
+ * Mirrors `app/src/lib/x1/namespaceRegister.ts`'s `namespaceSublabelShape` and
+ * the shape gate in `tools/api`'s `resolve`.
+ */
+export function scopedTldCandidate(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 sub = t.slice(0, dot);
+    const tld = t.slice(dot + 1);
+    if (sub.includes("."))
+        return null; // a deeper dotted name is a true sub-subname
+    if (RESERVED_SUFFIXES.has(tld))
+        return null; // never conflate with X1NS / external
+    if (tld.length > NAMESPACE_MAX_LEN)
+        return null;
+    if (!/^[a-z0-9-]+$/.test(tld))
+        return null;
+    if (tld.startsWith("-") || tld.endsWith("-") || tld.includes("--") || /^[0-9]+$/.test(tld)) {
+        return null;
+    }
+    return { sub, tld };
+}
+/**
+ * Whether a raw `Namespace` account's bytes say it is `Active`, byte-for-byte
+ * the authority's `namespace_active_from_bytes` (tools/api). Layout: disc(8) |
+ * label(Borsh `String`: u32 LE length + UTF-8 bytes) | status(u8), and
+ * `NamespaceStatus::Active` is the first enum variant (Borsh tag 0). Only the
+ * length prefix and the one status byte are parsed — nothing past it. `false`
+ * for any buffer too short to hold disc + length prefix + the status byte (a
+ * malformed/wrong account is never read as Active). The CALLER must also check
+ * the account is owned by the registry program — this reads bytes only.
+ */
+export function namespaceIsActive(data) {
+    if (data.length < 12)
+        return false;
+    const labelLen = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(8, true);
+    const statusOff = 12 + labelLen;
+    if (data.length <= statusOff)
+        return false;
+    return data[statusOff] === 0;
+}
+/**
+ * Build the default scoped-handle deriver using `@solana/web3.js`.
+ *
+ * Seeds are `["handle", label, name]` under the registry program — exactly the
+ * order `tools/api`'s `scoped_handle_pda` and the program's
+ * `register_under_namespace` use, so the derived PDA is the account the name
+ * actually lives at. Prefers an INJECTED web3 module (robust under `file:` /
+ * `npm link`, where a bare specifier resolves from THIS package's realpath, not
+ * the consumer's); falls back to a dynamic import for a normal install.
+ */
+export async function makeScopedHandleDeriver(web3Module) {
+    let web3;
+    if (web3Module) {
+        web3 = web3Module;
+    }
+    else {
+        const spec = "@solana/web3.js";
+        try {
+            web3 = (await import(spec));
+        }
+        catch {
+            throw new ResolveError("not-configured", "scoped TLD resolution needs a deriver: install @solana/web3.js, pass the web3 module to makeScopedHandleDeriver, or inject `scopedHandleDeriver` in the resolver config");
+        }
+    }
+    const enc = new TextEncoder();
+    const handleSeed = enc.encode("handle");
+    return {
+        scopedHandleKey(label, name, programId) {
+            const program = new web3.PublicKey(programId);
+            const [key] = web3.PublicKey.findProgramAddressSync([handleSeed, enc.encode(label), enc.encode(name)], program);
+            return key.toBase58();
+        },
+    };
+}

package/dist/types.d.ts

@@ -1,8 +1,18 @@
-/** Which naming system produced a result. */
-export type Namespace = "handle" | "x1" | "xnt" | "xen";
+/**
+ * Which naming system produced a result.
+ *
+ * The first four are the fixed native namespaces. A SCOPED customer-TLD name
+ * (`alices.testtld`, #8484/#8485) carries its TLD LABEL here — an arbitrary,
+ * launch-time string — so the union is widened with `(string & {})`: literal
+ * autocomplete for the fixed four is preserved, while a scoped result can set
+ * `namespace` to its `.tld`. Compare against the literals as before; a value
+ * that is none of them is a scoped TLD label.
+ */
+export type Namespace = "handle" | "x1" | "xnt" | "xen" | (string & {});
 /**
  * Display label for a namespace. **Must be shown** next to any resolved
- * address — see the module docs on why this is not optional.
+ * address — see the module docs on why this is not optional. A scoped TLD label
+ * renders as `.<label>` (e.g. `.testtld`), the same as an X1NS suffix.
  */
 export declare function namespaceLabel(ns: Namespace): string;
 /** Confidence in the address a name resolves to. */
@@ -83,7 +93,16 @@ export interface Resolved {
 /** Chains a handle can carry a record for. SLIP-44 based. */
 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";
+export type ResolveErrorCode = "unrecognized" | "ambiguous" | "invalid-handle" | "invalid-domain" | "not-found" | "no-record-for-chain" | "rpc-error"
+/**
+ * A reachable namespace exists for this name, but the adapter that would
+ * resolve it is not configured on this deployment (e.g. no `ETH_RPC_URL` for
+ * ENS, or no Solana mainnet RPC for SNS). Distinct from `unrecognized`: the
+ * name IS a known namespace — we just cannot reach its chain from here. A UI
+ * should surface "this namespace isn't enabled", not "unknown name", and the
+ * universal resolver NEVER fabricates an address to paper over it.
+ */
+ | "not-configured";
 /**
  * Finer-grained cause for a `ResolveError`, when the code alone is not
  * enough for a UI to explain what happened.