@x1id/resolve 0.2.1 → 0.6.0

package/dist/subname.d.ts

@@ -0,0 +1,282 @@
+/**
+ * On-chain subnames (#7375): a label under a parent `@handle`, e.g. `pay`
+ * under `alice` → `pay.alice`. Instruction builders, account decoding, and —
+ * critically — resolution with the TWO-LAYER staleness rule of
+ * docs/record-trust.md structurally enforced.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. Builders return the transport-neutral
+ * {@link BuiltInstruction} (see `delegate.ts`'s module docs for the two-line
+ * web3.js adapter).
+ *
+ * # What a subname is (mirror of the on-chain [`Subname`] doc, state.rs)
+ *
+ * - A single label under a parent handle, same character rules as a handle
+ *   label ({@link normalizeHandle}); ONE level deep (a subname cannot have
+ *   subnames — the program takes a `Handle` as parent, never a `Subname`).
+ * - It can hold cross-chain address `Record`s (the SAME account type handle
+ *   records use, seeded from the subname's pubkey), but can NEVER be a primary
+ *   name or be listed/offered/auctioned.
+ * - It has no owner of its own: the parent handle's CURRENT authority controls
+ *   it and may revoke it unilaterally (subject only to the parent's own #7377
+ *   lock — while locked, its whole subtree is frozen). Rent-only to create.
+ *
+ * # Deriving the PDAs — do it with your runtime, not here
+ *
+ * Like `delegate.ts`, this module does NOT derive PDAs (find_program_address
+ * needs an on-curve check this zero-dependency package refuses to hand-roll —
+ * see `wasm.ts`). Derive with your runtime, e.g. web3.js:
+ *
+ * ```ts
+ * // subname account
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(SUBNAME_SEED), parentHandlePda.toBytes(), Buffer.from(label, "utf8")],
+ *   programId,
+ * );
+ * // a record under a subname (the SAME "record" seed handle records use,
+ * // only the subname pubkey stands in for the handle)
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from("record"), subnamePda.toBytes(), new Uint8Array(new Uint32Array([coinType]).buffer)],
+ *   programId,
+ * );
+ * ```
+ *
+ * The label is used as a PDA seed DIRECTLY (no hash): a canonical label is
+ * ≤ 32 bytes, so it fits one seed — unlike a text-record key (up to 64,
+ * hashed).
+ *
+ * # The two-layer staleness rule — BOTH are mandatory
+ *
+ * A subname carries no owner, so the universal rule (docs/record-trust.md) is
+ * applied through the subname's `createdAt` in two places. A subname record is
+ * the current name's address ONLY when BOTH hold:
+ *
+ * 1. `subname.createdAt >= parent.registeredAt` — the subname belongs to the
+ *    parent's CURRENT owner. Any parent transfer/sale/recovery/re-registration
+ *    bumps `parent.registeredAt`, stranding every subname the previous owner
+ *    made (design point #4: never resolves to a stale owner after transfer).
+ * 2. `record.updatedAt >= subname.createdAt` — the record belongs to the
+ *    CURRENT incarnation of the subname (its `["subname", parent, label]` PDA
+ *    is reused across revoke + re-create, so a record left by a previous
+ *    incarnation must go stale under the new one).
+ *
+ * {@link resolveSubnameRecords} enforces BOTH. A reader that applies only one
+ * reopens the exact money-misdirection hazard the rule exists to close.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import { type HandleRecord } from "./records.js";
+import type { RpcFn } from "./accounts.js";
+/** Seed prefix of a subname PDA: `["subname", parentHandlePda, label]`. */
+export declare const SUBNAME_SEED = "subname";
+/** Anchor account discriminator: `sha256("account:Subname")[0..8]`. */
+export declare const SUBNAME_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:create_subname")[0..8]`. */
+export declare const CREATE_SUBNAME_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:revoke_subname")[0..8]`. */
+export declare const REVOKE_SUBNAME_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:create_subname_record")[0..8]`. */
+export declare const CREATE_SUBNAME_RECORD_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:update_subname_record")[0..8]`. */
+export declare const UPDATE_SUBNAME_RECORD_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:close_subname_record")[0..8]`. */
+export declare const CLOSE_SUBNAME_RECORD_DISCRIMINATOR: Uint8Array;
+/** `Subname` account size: disc(8) parent(32) label[32] label_len(1)
+ *  created_at(i64,8) bump(1). */
+export declare const SUBNAME_LEN = 82;
+/** Max label bytes — same as a handle label (`handle_normalize::MAX_LEN`). */
+export declare const SUBNAME_LABEL_MAX_LEN = 32;
+/** A decoded `Subname` account. */
+export interface Subname {
+    /** The parent `Handle` PDA this subname hangs under (base58). */
+    readonly parent: string;
+    /** The subname's label, plaintext (e.g. `"pay"`). */
+    readonly label: string;
+    /**
+     * Unix seconds this subname was (last) created. THE staleness anchor:
+     * trust the subname only while `createdAt >= parent.registeredAt`, and trust
+     * its records only while `record.updatedAt >= createdAt`. See the module
+     * docs.
+     */
+    readonly createdAt: bigint;
+    readonly bump: number;
+}
+/**
+ * Decode a `Subname` account's raw data (exactly what `getAccountInfo`
+ * returns for the `["subname", parent, label]` PDA), or null if the bytes are
+ * not a `Subname`.
+ */
+export declare function decodeSubname(data: Uint8Array): Subname | null;
+/**
+ * Whether a subname belongs to its parent's CURRENT owner — staleness layer 1
+ * (see the module docs). `parentRegisteredAt` is `Handle.registered_at` from
+ * the parent account the caller already has. A subname that fails this belongs
+ * to a PREVIOUS owner of the parent name and must never be resolved.
+ */
+export declare function subnameIsLive(subname: Subname, parentRegisteredAt: bigint): boolean;
+/** Fields shared by every subname builder that gates on parent authority. */
+interface ParentAuthorityParams {
+    /** TOKENIZED parent only: the holder's ATA for the parent's NFT mint,
+     *  appended as the strict-authority remaining-account proof. Omit for an
+     *  untokenized parent. */
+    readonly holderTokenAccount?: AddressLike;
+}
+export interface CreateSubnameParams extends ParentAuthorityParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the subname account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The parent handle's CURRENT authority (owner, or NFT holder). Signer. */
+    readonly owner: AddressLike;
+    /** The parent `["handle", name]` PDA. */
+    readonly parent: AddressLike;
+    /** The `["subname", parent, label]` PDA — derive per the module docs. */
+    readonly subname: AddressLike;
+    /** The subname's label (canonical, 1..=32 bytes — same rules as a handle
+     *  label). Feeds both the PDA seed and the stored field. */
+    readonly label: string;
+}
+/**
+ * Build `create_subname` — create `label` under the parent. Rent-only,
+ * parent-owner-gated, refused while the parent is #7377-locked.
+ */
+export declare function buildCreateSubnameIx(p: CreateSubnameParams): BuiltInstruction;
+export interface RevokeSubnameParams extends ParentAuthorityParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The parent handle's CURRENT authority. Signer. */
+    readonly owner: AddressLike;
+    /** The parent `["handle", name]` PDA. */
+    readonly parent: AddressLike;
+    /** The `["subname", parent, label]` PDA being closed. */
+    readonly subname: AddressLike;
+    /** Receives the closed subname's rent — any account the caller chooses. */
+    readonly recipient: AddressLike;
+}
+/**
+ * Build `revoke_subname` — delete the subname, rent to `recipient`. No
+ * independent-owner consent or records-must-be-empty condition; also how a NEW
+ * parent owner sweeps a previous owner's stale subname. REVERTS `HandleLocked`
+ * while the parent is #7377-locked (STRICT FREEZE, owner decision F1): a locked
+ * handle's whole subtree is frozen — unlock first, then revoke. A post-transfer
+ * new owner is never locked, so cleanup after a transfer is unaffected.
+ *
+ * NOTE: any `Record`s under the subname are NOT closed by this — close them
+ * first with {@link buildCloseSubnameRecordIx} for rent hygiene (they are
+ * resolution-safe if left, but their rent stays locked). Enumerate them with
+ * {@link fetchSubnameRecords}.
+ */
+export declare function buildRevokeSubnameIx(p: RevokeSubnameParams): BuiltInstruction;
+export interface CreateSubnameRecordParams extends ParentAuthorityParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the record's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The parent handle's CURRENT authority. Signer. */
+    readonly owner: AddressLike;
+    /** The parent `["handle", name]` PDA. */
+    readonly parent: AddressLike;
+    /** The `["subname", parent, label]` PDA. */
+    readonly subname: AddressLike;
+    /** The `["record", subname, coinType]` PDA — derive per the module docs. */
+    readonly record: AddressLike;
+    /** SLIP-44 / ENSIP-11 coin type. */
+    readonly coinType: number;
+    /** The address bytes (1..=64) — same encoding as a handle `Record`. */
+    readonly value: Uint8Array;
+}
+/**
+ * Build `create_subname_record` — a cross-chain address `Record` under the
+ * subname. Refused if the subname is stale
+ * (`subname.createdAt < parent.registeredAt`).
+ */
+export declare function buildCreateSubnameRecordIx(p: CreateSubnameRecordParams): BuiltInstruction;
+export interface UpdateSubnameRecordParams extends ParentAuthorityParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The parent handle's CURRENT authority. Signer. */
+    readonly owner: AddressLike;
+    /** The parent `["handle", name]` PDA. */
+    readonly parent: AddressLike;
+    /** The `["subname", parent, label]` PDA. */
+    readonly subname: AddressLike;
+    /** The `["record", subname, coinType]` PDA being updated. */
+    readonly record: AddressLike;
+    /** The new address bytes (1..=64). */
+    readonly value: Uint8Array;
+}
+/**
+ * Build `update_subname_record` — replace the address and re-stamp
+ * `updated_at` (also how a record is re-adopted after a fresh
+ * `create_subname`). Refused if the subname is stale.
+ */
+export declare function buildUpdateSubnameRecordIx(p: UpdateSubnameRecordParams): BuiltInstruction;
+export interface CloseSubnameRecordParams extends ParentAuthorityParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The parent handle's CURRENT authority. Signer. */
+    readonly owner: AddressLike;
+    /** The parent `["handle", name]` PDA. */
+    readonly parent: AddressLike;
+    /** The `["subname", parent, label]` PDA. */
+    readonly subname: AddressLike;
+    /** The `["record", subname, coinType]` PDA being closed. */
+    readonly record: AddressLike;
+    /** Receives the closed record's rent. */
+    readonly recipient: AddressLike;
+}
+/**
+ * Build `close_subname_record` — close the record, rent to `recipient`. No
+ * stale-subname gate (a stale subname's records must always be cleanable), but
+ * REVERTS `HandleLocked` while the parent is #7377-locked (STRICT FREEZE, owner
+ * decision F1) — unlock the parent first. A post-transfer new owner is not
+ * locked, so cleanup after a transfer is unaffected.
+ */
+export declare function buildCloseSubnameRecordIx(p: CloseSubnameRecordParams): BuiltInstruction;
+/**
+ * Fetch every `Subname` account of a parent handle — one `getProgramAccounts`
+ * call, filtered by size, the Subname discriminator at offset 0, and the
+ * parent pubkey at offset 8, then every byte re-checked locally. Scoping the
+ * scan to the registry program id IS the ownership check.
+ *
+ * `parentRegisteredAt` is `Handle.registered_at` from the parent account the
+ * caller already has. Every subname is returned with a `live` flag
+ * (`createdAt >= parentRegisteredAt`, staleness layer 1); a stale one belongs
+ * to a previous owner of the parent name and must never be resolved — surface
+ * it only to the current owner as "left behind; you can revoke this".
+ */
+export declare function fetchSubnames(rpc: RpcFn, programId: string, parentHandleAccount: string, parentRegisteredAt: bigint): Promise<(Subname & {
+    account: string;
+    live: boolean;
+})[]>;
+/**
+ * Fetch every `Record` account hanging off a SUBNAME — reuses the handle
+ * record scanner verbatim, because subname records ARE `Record` accounts whose
+ * `handle` field is the subname pubkey. Passing `subname.createdAt` as the
+ * epoch applies staleness layer 2 (`record.updatedAt >= subname.createdAt`):
+ * a record left by a previous incarnation of the same subname label is
+ * flagged `stale` (and its `verified` forced false).
+ *
+ * This does NOT apply layer 1 (subname-vs-parent). Use
+ * {@link resolveSubnameRecords} for the complete, safe resolution — or gate
+ * this call on {@link subnameIsLive} yourself.
+ *
+ * `recordsClearedAt` is fixed at `0n`, not the parent handle's: `clear_records`
+ * (#8139) only ever writes the PARENT `Handle` account's own extension — a
+ * subname is a separate account with no `records_cleared_at` of its own, so
+ * the parent's clear has no bearing on records keyed by the subname's pubkey.
+ */
+export declare function fetchSubnameRecords(rpc: RpcFn, programId: string, subnameAccount: string, subnameCreatedAt: bigint): Promise<HandleRecord[]>;
+/**
+ * Resolve a subname's LIVE address records — the ONLY safe entry point, both
+ * staleness layers enforced:
+ *
+ *   1. if `subname.createdAt < parentRegisteredAt` the subname is stale →
+ *      returns `[]` (it belongs to a previous parent owner);
+ *   2. otherwise its records are fetched with `subname.createdAt` as the epoch,
+ *      so a record from a previous incarnation of the subname is dropped.
+ *
+ * Returns only records the current name actually resolves to (stale ones
+ * excluded, `verified` already forced false for any that slipped the filter).
+ */
+export declare function resolveSubnameRecords(rpc: RpcFn, programId: string, subnameAccount: string, subname: Subname, parentRegisteredAt: bigint): Promise<HandleRecord[]>;
+export {};

package/dist/subname.js

@@ -0,0 +1,371 @@
+/**
+ * On-chain subnames (#7375): a label under a parent `@handle`, e.g. `pay`
+ * under `alice` → `pay.alice`. Instruction builders, account decoding, and —
+ * critically — resolution with the TWO-LAYER staleness rule of
+ * docs/record-trust.md structurally enforced.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. Builders return the transport-neutral
+ * {@link BuiltInstruction} (see `delegate.ts`'s module docs for the two-line
+ * web3.js adapter).
+ *
+ * # What a subname is (mirror of the on-chain [`Subname`] doc, state.rs)
+ *
+ * - A single label under a parent handle, same character rules as a handle
+ *   label ({@link normalizeHandle}); ONE level deep (a subname cannot have
+ *   subnames — the program takes a `Handle` as parent, never a `Subname`).
+ * - It can hold cross-chain address `Record`s (the SAME account type handle
+ *   records use, seeded from the subname's pubkey), but can NEVER be a primary
+ *   name or be listed/offered/auctioned.
+ * - It has no owner of its own: the parent handle's CURRENT authority controls
+ *   it and may revoke it unilaterally (subject only to the parent's own #7377
+ *   lock — while locked, its whole subtree is frozen). Rent-only to create.
+ *
+ * # Deriving the PDAs — do it with your runtime, not here
+ *
+ * Like `delegate.ts`, this module does NOT derive PDAs (find_program_address
+ * needs an on-curve check this zero-dependency package refuses to hand-roll —
+ * see `wasm.ts`). Derive with your runtime, e.g. web3.js:
+ *
+ * ```ts
+ * // subname account
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(SUBNAME_SEED), parentHandlePda.toBytes(), Buffer.from(label, "utf8")],
+ *   programId,
+ * );
+ * // a record under a subname (the SAME "record" seed handle records use,
+ * // only the subname pubkey stands in for the handle)
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from("record"), subnamePda.toBytes(), new Uint8Array(new Uint32Array([coinType]).buffer)],
+ *   programId,
+ * );
+ * ```
+ *
+ * The label is used as a PDA seed DIRECTLY (no hash): a canonical label is
+ * ≤ 32 bytes, so it fits one seed — unlike a text-record key (up to 64,
+ * hashed).
+ *
+ * # The two-layer staleness rule — BOTH are mandatory
+ *
+ * A subname carries no owner, so the universal rule (docs/record-trust.md) is
+ * applied through the subname's `createdAt` in two places. A subname record is
+ * the current name's address ONLY when BOTH hold:
+ *
+ * 1. `subname.createdAt >= parent.registeredAt` — the subname belongs to the
+ *    parent's CURRENT owner. Any parent transfer/sale/recovery/re-registration
+ *    bumps `parent.registeredAt`, stranding every subname the previous owner
+ *    made (design point #4: never resolves to a stale owner after transfer).
+ * 2. `record.updatedAt >= subname.createdAt` — the record belongs to the
+ *    CURRENT incarnation of the subname (its `["subname", parent, label]` PDA
+ *    is reused across revoke + re-create, so a record left by a previous
+ *    incarnation must go stale under the new one).
+ *
+ * {@link resolveSubnameRecords} enforces BOTH. A reader that applies only one
+ * reopens the exact money-misdirection hazard the rule exists to close.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { fetchRecords } from "./records.js";
+/** Seed prefix of a subname PDA: `["subname", parentHandlePda, label]`. */
+export const SUBNAME_SEED = "subname";
+/** Anchor account discriminator: `sha256("account:Subname")[0..8]`. */
+export const SUBNAME_DISCRIMINATOR = Uint8Array.from([
+    139, 112, 87, 17, 41, 196, 150, 109,
+]);
+/** Anchor instruction discriminator: `sha256("global:create_subname")[0..8]`. */
+export const CREATE_SUBNAME_DISCRIMINATOR = Uint8Array.from([
+    171, 24, 16, 42, 114, 52, 73, 43,
+]);
+/** Anchor instruction discriminator: `sha256("global:revoke_subname")[0..8]`. */
+export const REVOKE_SUBNAME_DISCRIMINATOR = Uint8Array.from([
+    87, 101, 106, 225, 23, 207, 143, 114,
+]);
+/** Anchor instruction discriminator: `sha256("global:create_subname_record")[0..8]`. */
+export const CREATE_SUBNAME_RECORD_DISCRIMINATOR = Uint8Array.from([
+    105, 119, 250, 240, 198, 138, 84, 86,
+]);
+/** Anchor instruction discriminator: `sha256("global:update_subname_record")[0..8]`. */
+export const UPDATE_SUBNAME_RECORD_DISCRIMINATOR = Uint8Array.from([
+    41, 233, 2, 89, 35, 65, 253, 241,
+]);
+/** Anchor instruction discriminator: `sha256("global:close_subname_record")[0..8]`. */
+export const CLOSE_SUBNAME_RECORD_DISCRIMINATOR = Uint8Array.from([
+    124, 229, 58, 219, 15, 20, 159, 214,
+]);
+/** `Subname` account size: disc(8) parent(32) label[32] label_len(1)
+ *  created_at(i64,8) bump(1). */
+export const SUBNAME_LEN = 82;
+/** Max label bytes — same as a handle label (`handle_normalize::MAX_LEN`). */
+export const SUBNAME_LABEL_MAX_LEN = 32;
+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));
+}
+/** Borsh `String`/`Vec<u8>`: u32 LE length + bytes. */
+function encVec(bytes) {
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+/** u32 LE — the wire form of `coin_type`. */
+function encU32(n) {
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, n >>> 0, true);
+    return out;
+}
+/**
+ * Decode a `Subname` account's raw data (exactly what `getAccountInfo`
+ * returns for the `["subname", parent, label]` PDA), or null if the bytes are
+ * not a `Subname`.
+ */
+export function decodeSubname(data) {
+    if (data.length !== SUBNAME_LEN)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (data[i] !== SUBNAME_DISCRIMINATOR[i])
+            return null;
+    }
+    const labelLen = Math.min(data[72], SUBNAME_LABEL_MAX_LEN);
+    const label = new TextDecoder().decode(data.slice(40, 40 + labelLen));
+    const createdAt = new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(73, true);
+    return {
+        parent: encodeBase58(data.slice(8, 40)),
+        label,
+        createdAt,
+        bump: data[81],
+    };
+}
+/**
+ * Whether a subname belongs to its parent's CURRENT owner — staleness layer 1
+ * (see the module docs). `parentRegisteredAt` is `Handle.registered_at` from
+ * the parent account the caller already has. A subname that fails this belongs
+ * to a PREVIOUS owner of the parent name and must never be resolved.
+ */
+export function subnameIsLive(subname, parentRegisteredAt) {
+    return subname.createdAt >= parentRegisteredAt;
+}
+function pushHolderAta(keys, p) {
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({
+            pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"),
+            isSigner: false,
+            isWritable: false,
+        });
+    }
+}
+/**
+ * Build `create_subname` — create `label` under the parent. Rent-only,
+ * parent-owner-gated, refused while the parent is #7377-locked.
+ */
+export function buildCreateSubnameIx(p) {
+    const labelBytes = new TextEncoder().encode(p.label);
+    if (labelBytes.length === 0 || labelBytes.length > SUBNAME_LABEL_MAX_LEN) {
+        throw new Error(`label must be 1..=${SUBNAME_LABEL_MAX_LEN} bytes`);
+    }
+    const encLabel = encVec(labelBytes);
+    const data = new Uint8Array(8 + encLabel.length);
+    data.set(CREATE_SUBNAME_DISCRIMINATOR, 0);
+    data.set(encLabel, 8);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.parent, "parent"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.subname, "subname"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    pushHolderAta(keys, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `revoke_subname` — delete the subname, rent to `recipient`. No
+ * independent-owner consent or records-must-be-empty condition; also how a NEW
+ * parent owner sweeps a previous owner's stale subname. REVERTS `HandleLocked`
+ * while the parent is #7377-locked (STRICT FREEZE, owner decision F1): a locked
+ * handle's whole subtree is frozen — unlock first, then revoke. A post-transfer
+ * new owner is never locked, so cleanup after a transfer is unaffected.
+ *
+ * NOTE: any `Record`s under the subname are NOT closed by this — close them
+ * first with {@link buildCloseSubnameRecordIx} for rent hygiene (they are
+ * resolution-safe if left, but their rent stays locked). Enumerate them with
+ * {@link fetchSubnameRecords}.
+ */
+export function buildRevokeSubnameIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.parent, "parent"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.subname, "subname"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    pushHolderAta(keys, p);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: REVOKE_SUBNAME_DISCRIMINATOR.slice(),
+    };
+}
+/**
+ * Build `create_subname_record` — a cross-chain address `Record` under the
+ * subname. Refused if the subname is stale
+ * (`subname.createdAt < parent.registeredAt`).
+ */
+export function buildCreateSubnameRecordIx(p) {
+    if (p.value.length === 0 || p.value.length > 64) {
+        throw new Error("value must be 1..=64 bytes");
+    }
+    const encValue = encVec(p.value);
+    const data = new Uint8Array(8 + 4 + encValue.length);
+    data.set(CREATE_SUBNAME_RECORD_DISCRIMINATOR, 0);
+    data.set(encU32(p.coinType), 8);
+    data.set(encValue, 12);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.parent, "parent"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.subname, "subname"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    pushHolderAta(keys, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `update_subname_record` — replace the address and re-stamp
+ * `updated_at` (also how a record is re-adopted after a fresh
+ * `create_subname`). Refused if the subname is stale.
+ */
+export function buildUpdateSubnameRecordIx(p) {
+    if (p.value.length === 0 || p.value.length > 64) {
+        throw new Error("value must be 1..=64 bytes");
+    }
+    const encValue = encVec(p.value);
+    const data = new Uint8Array(8 + encValue.length);
+    data.set(UPDATE_SUBNAME_RECORD_DISCRIMINATOR, 0);
+    data.set(encValue, 8);
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.parent, "parent"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.subname, "subname"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushHolderAta(keys, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `close_subname_record` — close the record, rent to `recipient`. No
+ * stale-subname gate (a stale subname's records must always be cleanable), but
+ * REVERTS `HandleLocked` while the parent is #7377-locked (STRICT FREEZE, owner
+ * decision F1) — unlock the parent first. A post-transfer new owner is not
+ * locked, so cleanup after a transfer is unaffected.
+ */
+export function buildCloseSubnameRecordIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.parent, "parent"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.subname, "subname"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    pushHolderAta(keys, p);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: CLOSE_SUBNAME_RECORD_DISCRIMINATOR.slice(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+const SUBNAME_PARENT_OFFSET = 8; // `parent` field, right after the discriminator
+/**
+ * Fetch every `Subname` account of a parent handle — one `getProgramAccounts`
+ * call, filtered by size, the Subname discriminator at offset 0, and the
+ * parent pubkey at offset 8, then every byte re-checked locally. Scoping the
+ * scan to the registry program id IS the ownership check.
+ *
+ * `parentRegisteredAt` is `Handle.registered_at` from the parent account the
+ * caller already has. Every subname is returned with a `live` flag
+ * (`createdAt >= parentRegisteredAt`, staleness layer 1); a stale one belongs
+ * to a previous owner of the parent name and must never be resolved — surface
+ * it only to the current owner as "left behind; you can revoke this".
+ */
+export async function fetchSubnames(rpc, programId, parentHandleAccount, parentRegisteredAt) {
+    const res = (await rpc("getProgramAccounts", [
+        programId,
+        {
+            encoding: "base64",
+            commitment: "confirmed",
+            filters: [
+                { dataSize: SUBNAME_LEN },
+                { memcmp: { offset: 0, bytes: encodeBase58(SUBNAME_DISCRIMINATOR) } },
+                { memcmp: { offset: SUBNAME_PARENT_OFFSET, bytes: parentHandleAccount } },
+            ],
+        },
+    ]));
+    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 s = decodeSubname(raw);
+        // Defence in depth: the memcmp should guarantee the parent match, but a
+        // wrong offset would silently attribute someone else's subname here.
+        if (s && s.parent === parentHandleAccount) {
+            out.push({ ...s, account: a.pubkey, live: subnameIsLive(s, parentRegisteredAt) });
+        }
+    }
+    out.sort((x, y) => x.label.localeCompare(y.label));
+    return out;
+}
+/**
+ * Fetch every `Record` account hanging off a SUBNAME — reuses the handle
+ * record scanner verbatim, because subname records ARE `Record` accounts whose
+ * `handle` field is the subname pubkey. Passing `subname.createdAt` as the
+ * epoch applies staleness layer 2 (`record.updatedAt >= subname.createdAt`):
+ * a record left by a previous incarnation of the same subname label is
+ * flagged `stale` (and its `verified` forced false).
+ *
+ * This does NOT apply layer 1 (subname-vs-parent). Use
+ * {@link resolveSubnameRecords} for the complete, safe resolution — or gate
+ * this call on {@link subnameIsLive} yourself.
+ *
+ * `recordsClearedAt` is fixed at `0n`, not the parent handle's: `clear_records`
+ * (#8139) only ever writes the PARENT `Handle` account's own extension — a
+ * subname is a separate account with no `records_cleared_at` of its own, so
+ * the parent's clear has no bearing on records keyed by the subname's pubkey.
+ */
+export async function fetchSubnameRecords(rpc, programId, subnameAccount, subnameCreatedAt) {
+    // The record filter already includes size + Record discriminator; the
+    // handle-field memcmp is the subname pubkey here. Reuse the exact scanner so
+    // subname records and handle records can never decode differently.
+    return fetchRecords(rpc, programId, subnameAccount, subnameCreatedAt, 0n);
+}
+/**
+ * Resolve a subname's LIVE address records — the ONLY safe entry point, both
+ * staleness layers enforced:
+ *
+ *   1. if `subname.createdAt < parentRegisteredAt` the subname is stale →
+ *      returns `[]` (it belongs to a previous parent owner);
+ *   2. otherwise its records are fetched with `subname.createdAt` as the epoch,
+ *      so a record from a previous incarnation of the subname is dropped.
+ *
+ * Returns only records the current name actually resolves to (stale ones
+ * excluded, `verified` already forced false for any that slipped the filter).
+ */
+export async function resolveSubnameRecords(rpc, programId, subnameAccount, subname, parentRegisteredAt) {
+    if (!subnameIsLive(subname, parentRegisteredAt))
+        return [];
+    const records = await fetchSubnameRecords(rpc, programId, subnameAccount, subname.createdAt);
+    return records.filter((r) => !r.stale);
+}