@x1id/resolve 0.10.0 → 0.12.0

package/dist/lease.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Lease-to-own instructions (#8150, #8320) — the SIBLING of `register` for term
+ * leases, not a replacement: the permanent one-time `register` path
+ * (register.ts) is untouched and stays the default.
+ *
+ * - `register_leased` — claim an unregistered `["handle", name]` under a lease,
+ *   paying the first installment now.
+ * - `renew_lease` — pay more toward a leased handle. PERMISSIONLESS: the payer
+ *   need not be the owner (anyone may keep or pay off someone else's lease,
+ *   ENS-registrar-style).
+ * - `reclaim_expired_lease` — take over a leased handle whose grace period has
+ *   ENDED, under a FRESH lease; the reclaimer becomes `owner`. Also
+ *   permissionless. The program enforces `now >= expires_at + grace`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. PDAs are NOT derived here (see delegate.ts) — derive
+ * `["config"]` / `["handle", name]` with your runtime's `findProgramAddress`,
+ * and read `Config.treasury` with {@link fetchConfigTreasury} (register.ts).
+ *
+ * `payment` is in lamports — the amount accepted toward the lease now. The
+ * on-chain `lease_seconds_purchased` / `lease_accept_payment` logic converts it
+ * to lease-time, capped at the permanent price (offering the full permanent
+ * price up front settles the handle permanently in one instruction, writing
+ * `expires_at = 0`). This builder does not compute that split; simulate or
+ * mirror it client-side if you need to preview before signing.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { HandleTypeValue } from "./voucher.js";
+/** `sha256("global:register_leased")[0..8]`. */
+export declare const REGISTER_LEASED_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:renew_lease")[0..8]`. */
+export declare const RENEW_LEASE_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:reclaim_expired_lease")[0..8]`. */
+export declare const RECLAIM_EXPIRED_LEASE_DISCRIMINATOR: Uint8Array;
+export interface RegisterLeasedParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the first lease installment + the `Handle` account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign — may be registered on another's behalf. */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — read it fresh via {@link fetchConfigTreasury}. */
+    readonly treasury: AddressLike;
+    /** The `["handle", name]` PDA being claimed — must not already exist. */
+    readonly handle: AddressLike;
+    /** Canonical form (`parseName(...).canonical`), 1..=32 bytes. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** First lease payment, in lamports. `>= permanentPrice` settles it outright. */
+    readonly payment: bigint;
+}
+/** Build `register_leased`. Data: `disc ‖ borsh(name) ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export declare function buildRegisterLeasedIx(p: RegisterLeasedParams): BuiltInstruction;
+export interface RenewLeaseParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays toward the lease. Signer. PERMISSIONLESS — need NOT be the owner. */
+    readonly payer: AddressLike;
+    /** The `["config"]` PDA (read-only on this path). */
+    readonly config: AddressLike;
+    /** `Config.treasury` — the program address-constrains it to this, so it can't
+     *  be substituted; read it fresh via {@link fetchConfigTreasury}. */
+    readonly treasury: AddressLike;
+    /** The leased `["handle", name]` PDA being paid toward. */
+    readonly handle: AddressLike;
+    /** Lamports to accept toward the lease (capped at the permanent price on-chain). */
+    readonly payment: bigint;
+}
+/** Build `renew_lease`. Data: `disc ‖ payment(u64 LE)`. */
+export declare function buildRenewLeaseIx(p: RenewLeaseParams): BuiltInstruction;
+export interface ReclaimExpiredLeaseParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the fresh lease's first installment; becomes the new owner. Signer.
+     *  PERMISSIONLESS — anyone may reclaim a grace-ended leased handle. */
+    readonly payer: AddressLike;
+    /** The new owner (typically the same as `payer`). Need not sign. */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — address-constrained on-chain; {@link fetchConfigTreasury}. */
+    readonly treasury: AddressLike;
+    /** The leased `["handle", name]` PDA being reclaimed — its grace must have ended. */
+    readonly handle: AddressLike;
+    readonly handleType: HandleTypeValue;
+    /** The fresh lease's first payment, in lamports. */
+    readonly payment: bigint;
+}
+/** Build `reclaim_expired_lease`. Data: `disc ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export declare function buildReclaimExpiredLeaseIx(p: ReclaimExpiredLeaseParams): BuiltInstruction;

package/dist/lease.js

@@ -0,0 +1,117 @@
+/**
+ * Lease-to-own instructions (#8150, #8320) — the SIBLING of `register` for term
+ * leases, not a replacement: the permanent one-time `register` path
+ * (register.ts) is untouched and stays the default.
+ *
+ * - `register_leased` — claim an unregistered `["handle", name]` under a lease,
+ *   paying the first installment now.
+ * - `renew_lease` — pay more toward a leased handle. PERMISSIONLESS: the payer
+ *   need not be the owner (anyone may keep or pay off someone else's lease,
+ *   ENS-registrar-style).
+ * - `reclaim_expired_lease` — take over a leased handle whose grace period has
+ *   ENDED, under a FRESH lease; the reclaimer becomes `owner`. Also
+ *   permissionless. The program enforces `now >= expires_at + grace`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. PDAs are NOT derived here (see delegate.ts) — derive
+ * `["config"]` / `["handle", name]` with your runtime's `findProgramAddress`,
+ * and read `Config.treasury` with {@link fetchConfigTreasury} (register.ts).
+ *
+ * `payment` is in lamports — the amount accepted toward the lease now. The
+ * on-chain `lease_seconds_purchased` / `lease_accept_payment` logic converts it
+ * to lease-time, capped at the permanent price (offering the full permanent
+ * price up front settles the handle permanently in one instruction, writing
+ * `expires_at = 0`). This builder does not compute that split; simulate or
+ * mirror it client-side if you need to preview before signing.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** `sha256("global:register_leased")[0..8]`. */
+export const REGISTER_LEASED_DISCRIMINATOR = Uint8Array.from([83, 192, 142, 193, 191, 53, 8, 15]);
+/** `sha256("global:renew_lease")[0..8]`. */
+export const RENEW_LEASE_DISCRIMINATOR = Uint8Array.from([11, 121, 141, 53, 216, 217, 123, 139]);
+/** `sha256("global:reclaim_expired_lease")[0..8]`. */
+export const RECLAIM_EXPIRED_LEASE_DISCRIMINATOR = Uint8Array.from([66, 80, 245, 8, 1, 21, 161, 110]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+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 assertHandleType(t) {
+    if (!Number.isInteger(t) || t < 0 || t > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+}
+function encodeName(name) {
+    const b = new TextEncoder().encode(name);
+    if (b.length < 1 || b.length > 32)
+        throw new Error("name must be 1..=32 bytes (UTF-8)");
+    return b;
+}
+function u64le(n) {
+    if (n < 0n)
+        throw new Error("payment must be a non-negative u64 (lamports)");
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, n, true);
+    return b;
+}
+/** Build `register_leased`. Data: `disc ‖ borsh(name) ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export function buildRegisterLeasedIx(p) {
+    assertHandleType(p.handleType);
+    const nb = encodeName(p.name);
+    const data = new Uint8Array(8 + 4 + nb.length + 1 + 8);
+    data.set(REGISTER_LEASED_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nb.length, true);
+    data.set(nb, 12);
+    data[12 + nb.length] = p.handleType;
+    data.set(u64le(p.payment), 12 + nb.length + 1);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), 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 };
+}
+/** Build `renew_lease`. Data: `disc ‖ payment(u64 LE)`. */
+export function buildRenewLeaseIx(p) {
+    const data = new Uint8Array(8 + 8);
+    data.set(RENEW_LEASE_DISCRIMINATOR, 0);
+    data.set(u64le(p.payment), 8);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.treasury, "treasury"), 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 };
+}
+/** Build `reclaim_expired_lease`. Data: `disc ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export function buildReclaimExpiredLeaseIx(p) {
+    assertHandleType(p.handleType);
+    const data = new Uint8Array(8 + 1 + 8);
+    data.set(RECLAIM_EXPIRED_LEASE_DISCRIMINATOR, 0);
+    data[8] = p.handleType;
+    data.set(u64le(p.payment), 9);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), 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 };
+}

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