@x1id/resolve 0.3.0 → 0.6.0

package/dist/records.d.ts

@@ -19,6 +19,15 @@
  * There is deliberately no way to decode or fetch a record through this
  * module without the handle's `registered_at` in hand, mirroring
  * app/src/lib/x1/records.ts. See docs/record-trust.md for the full argument.
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer. The same functions therefore also demand the handle's
+ * `recordsClearedAt` (0 if never cleared, from `ParsedHandle`) and a record
+ * is `stale` when EITHER `updated_at < registeredAt` OR
+ * `updated_at < recordsClearedAt` — see `Handle::read_records_cleared_at`'s
+ * doc comment in state.rs.
  */
 import { type Chain } from "./types.js";
 import type { RpcFn } from "./accounts.js";
@@ -75,7 +84,10 @@ export interface HandleRecord {
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
  * caller from the Handle account — it decides `stale` (and so `verified`).
- * There is intentionally no overload without it.
+ * `recordsClearedAt` is the same Handle's `recordsClearedAt` (0 if never
+ * cleared, #8139) — a SECOND, independent staleness anchor, checked
+ * alongside (not instead of) `registeredAt`. There is intentionally no
+ * overload without either.
  *
  * Returns null for anything that is not a Record: wrong length, wrong
  * discriminator, or a `value` length that does not fit. The Listing / Offer /
@@ -83,7 +95,7 @@ export interface HandleRecord {
  * so a handle-only memcmp scan DOES return them — they are rejected here by
  * tag and size, not by luck.
  */
-export declare function decodeRecord(raw: Uint8Array, account: string, registeredAt: bigint): HandleRecord | null;
+export declare function decodeRecord(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: bigint): HandleRecord | null;
 /** The records the CURRENT owner actually has — `stale` ones excluded. This
  *  is the list to resolve against, display to a visitor, and count. */
 export declare function liveRecords(records: readonly HandleRecord[]): HandleRecord[];
@@ -105,9 +117,14 @@ export declare function valueToAddress(chain: Chain | null, value: Uint8Array):
  *
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
- * is no variant of this function without it. Every record is returned,
- * stale ones flagged (`verified` already forced false), so an owner surface
- * can show what a previous owner left behind; anything that resolves,
- * displays to a visitor, or counts takes `liveRecords(...)`.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it, not a
+ * literal 0, unless the records being fetched genuinely hang off a DIFFERENT
+ * account than the one `clear_records` could ever touch (e.g. a subname's
+ * own records, keyed by the subname's `createdAt` instead — see
+ * `subname.ts`). Every record is returned, stale ones flagged (`verified`
+ * already forced false), so an owner surface can show what a previous owner
+ * left behind; anything that resolves, displays to a visitor, or counts
+ * takes `liveRecords(...)`.
  */
-export declare function fetchRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint): Promise<HandleRecord[]>;
+export declare function fetchRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint): Promise<HandleRecord[]>;

package/dist/records.js

@@ -19,6 +19,15 @@
  * There is deliberately no way to decode or fetch a record through this
  * module without the handle's `registered_at` in hand, mirroring
  * app/src/lib/x1/records.ts. See docs/record-trust.md for the full argument.
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer. The same functions therefore also demand the handle's
+ * `recordsClearedAt` (0 if never cleared, from `ParsedHandle`) and a record
+ * is `stale` when EITHER `updated_at < registeredAt` OR
+ * `updated_at < recordsClearedAt` — see `Handle::read_records_cleared_at`'s
+ * doc comment in state.rs.
  */
 import { encodeBase58 } from "./base58.js";
 import { CHAIN_COIN_TYPE } from "./types.js";
@@ -52,7 +61,10 @@ export function chainForCoinType(coinType) {
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
  * caller from the Handle account — it decides `stale` (and so `verified`).
- * There is intentionally no overload without it.
+ * `recordsClearedAt` is the same Handle's `recordsClearedAt` (0 if never
+ * cleared, #8139) — a SECOND, independent staleness anchor, checked
+ * alongside (not instead of) `registeredAt`. There is intentionally no
+ * overload without either.
  *
  * Returns null for anything that is not a Record: wrong length, wrong
  * discriminator, or a `value` length that does not fit. The Listing / Offer /
@@ -60,7 +72,7 @@ export function chainForCoinType(coinType) {
  * so a handle-only memcmp scan DOES return them — they are rejected here by
  * tag and size, not by luck.
  */
-export function decodeRecord(raw, account, registeredAt) {
+export function decodeRecord(raw, account, registeredAt, recordsClearedAt) {
     if (raw.length !== RECORD_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -83,7 +95,7 @@ export function decodeRecord(raw, account, registeredAt) {
     const verified = raw[o] === 1;
     o += 1;
     const updatedAt = dv.getBigInt64(o, true);
-    const stale = updatedAt < registeredAt;
+    const stale = updatedAt < registeredAt || updatedAt < recordsClearedAt;
     const chain = chainForCoinType(coinType);
     return {
         account,
@@ -142,12 +154,17 @@ function hexToBytes(hex) {
  *
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
- * is no variant of this function without it. Every record is returned,
- * stale ones flagged (`verified` already forced false), so an owner surface
- * can show what a previous owner left behind; anything that resolves,
- * displays to a visitor, or counts takes `liveRecords(...)`.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it, not a
+ * literal 0, unless the records being fetched genuinely hang off a DIFFERENT
+ * account than the one `clear_records` could ever touch (e.g. a subname's
+ * own records, keyed by the subname's `createdAt` instead — see
+ * `subname.ts`). Every record is returned, stale ones flagged (`verified`
+ * already forced false), so an owner surface can show what a previous owner
+ * left behind; anything that resolves, displays to a visitor, or counts
+ * takes `liveRecords(...)`.
  */
-export async function fetchRecords(rpc, programId, handleAccount, registeredAt) {
+export async function fetchRecords(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -166,7 +183,7 @@ export async function fetchRecords(rpc, programId, handleAccount, registeredAt)
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const r = decodeRecord(raw, a.pubkey, registeredAt);
+        const r = decodeRecord(raw, a.pubkey, registeredAt, recordsClearedAt);
         // Defence in depth: the memcmp filter should guarantee the handle match,
         // but a wrong offset would silently attribute someone else's record to
         // this handle. A malformed account is skipped, not fatal to the list.

package/dist/register.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `register` — the core write instruction: pay the current ramp price and
+ * claim an unregistered `["handle", name]` PDA. Every other write path in
+ * this SDK (voucher, subname, lock, delegate, attestation, text record,
+ * integrator) already has a builder; this was the one gap.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. PDAs are NOT derived here (see delegate.ts's
+ * module docs for why) — derive `["config"]` / `["handle", name]` with your
+ * runtime's canonical `findProgramAddress`.
+ *
+ * `register`'s price is computed ON-CHAIN at execution time (time + volume
+ * ramp over `Config.tier_lamports`) — there is no client-supplied price or
+ * slippage parameter; the payer simply pays whatever the program charges as
+ * of the landing slot. {@link fetchConfigTreasury} reads the one `Config`
+ * field this builder needs (the treasury address every registration pays).
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+import type { HandleTypeValue } from "./voucher.js";
+/** Anchor instruction discriminator: `sha256("global:register")[0..8]`. */
+export declare const REGISTER_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:register_with_forti")[0..8]`. */
+export declare const REGISTER_WITH_FORTI_DISCRIMINATOR: Uint8Array;
+/**
+ * Read `Config.treasury` — the account every `register` call pays — given
+ * the `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ * shaped like a `Config` (too short to hold `treasury`).
+ */
+export declare function fetchConfigTreasury(rpc: RpcFn, configAccount: string): Promise<string | null>;
+export interface RegisterParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the registration fee and the `Handle` account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign — a handle can be registered on
+     *  someone else's behalf (gifting, merchant onboarding). */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — read it fresh via {@link fetchConfigTreasury}
+     *  (it's admin-rotatable, so don't cache it across a session). */
+    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;
+    /** OPTIONAL revenue-share pair (#7397) — supply BOTH or NEITHER; supplying
+     *  exactly one fails on-chain (`IntegratorNotAllowed`). */
+    readonly integrator?: AddressLike;
+    /** The `["integrator", integrator]` allowlist PDA. */
+    readonly integratorAllowlist?: AddressLike;
+}
+/**
+ * Build `register`. Price is computed on-chain (see the module docs) — this
+ * builder does not know or assert it; simulate first if you need to show the
+ * payer a price before they sign.
+ */
+export declare function buildRegisterIx(p: RegisterParams): 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
+ *  `ZeroFortiRate` gate the program itself enforces; callers should refuse
+ *  to build the instruction rather than let it fail on-chain. */
+export interface ConfigForti {
+    readonly fortiMint: string;
+    readonly fortiTreasuryAta: string;
+    readonly veFortiProgram: string;
+    readonly fortiBuybackRecipient: string;
+    readonly fortiRatePerLamport: bigint;
+}
+/** Read the `Config` fields a `register_with_forti` build needs, given the
+ *  `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ *  shaped like a post-#8136 `Config` (too short to hold these fields —
+ *  e.g. a `Config` that hasn't run `migrate_config_v4` yet). */
+export declare function fetchConfigForti(rpc: RpcFn, configAccount: string): Promise<ConfigForti | null>;
+export interface RegisterWithFortiParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the FORTI amount and the `Handle` account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign — same as {@link RegisterParams.owner}. */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.forti_mint` — {@link fetchConfigForti}. */
+    readonly fortiMint: AddressLike;
+    /** The PAYER's associated token account for `fortiMint` — derive with your
+     *  runtime's canonical ATA derivation (Token-2022; the real testnet FORTI
+     *  mint is Token-2022, not classic SPL Token). */
+    readonly payerFortiAccount: AddressLike;
+    /** `Config.forti_treasury_ata` — {@link fetchConfigForti}. */
+    readonly fortiTreasuryAta: AddressLike;
+    /** `Config.forti_buyback_recipient` — {@link fetchConfigForti}. */
+    readonly fortiBuybackRecipient: AddressLike;
+    /** The payer's veFORTI lock PDA (`["lock", payer]` under
+     *  `Config.veforti_program`) — may not exist (payer never locked), in
+     *  which case the program treats voting power as zero. Derive with your
+     *  runtime's canonical `findProgramAddress` against
+     *  `fetchConfigForti(...).veFortiProgram`. */
+    readonly veFortiLock: 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;
+    /** The token program that owns `fortiMint` — Token-2022 on testnet today;
+     *  pass whichever `fortiMint`'s own `owner` field names, never hardcode. */
+    readonly tokenProgram: AddressLike;
+}
+/**
+ * Build `register_with_forti` (#8136) — a SIBLING payment path to
+ * `register`, not a replacement. Price is computed on-chain the same way
+ * `register`'s is (see that builder's docs) — this builder does not know or
+ * assert it; use `/quote/:name?pay_with=forti[&payer=...]` (tools/api) or
+ * simulate first if you need to show the payer a price before they sign.
+ */
+export declare function buildRegisterWithFortiIx(p: RegisterWithFortiParams): BuiltInstruction;

package/dist/register.js

@@ -0,0 +1,183 @@
+/**
+ * `register` — the core write instruction: pay the current ramp price and
+ * claim an unregistered `["handle", name]` PDA. Every other write path in
+ * this SDK (voucher, subname, lock, delegate, attestation, text record,
+ * integrator) already has a builder; this was the one gap.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. PDAs are NOT derived here (see delegate.ts's
+ * module docs for why) — derive `["config"]` / `["handle", name]` with your
+ * runtime's canonical `findProgramAddress`.
+ *
+ * `register`'s price is computed ON-CHAIN at execution time (time + volume
+ * ramp over `Config.tier_lamports`) — there is no client-supplied price or
+ * slippage parameter; the payer simply pays whatever the program charges as
+ * of the landing slot. {@link fetchConfigTreasury} reads the one `Config`
+ * field this builder needs (the treasury address every registration pays).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Anchor instruction discriminator: `sha256("global:register")[0..8]`. */
+export const REGISTER_DISCRIMINATOR = Uint8Array.from([
+    211, 124, 67, 15, 211, 194, 178, 240,
+]);
+/** Anchor instruction discriminator: `sha256("global:register_with_forti")[0..8]`. */
+export const REGISTER_WITH_FORTI_DISCRIMINATOR = Uint8Array.from([
+    48, 73, 211, 175, 49, 236, 133, 82,
+]);
+/** Byte offset of `treasury` within a `Config` account (after the 8-byte
+ *  discriminator: `admin: Pubkey(32)` then `treasury: Pubkey(32)` at 40). */
+const CONFIG_TREASURY_OFFSET = 40;
+const PUBKEY_LEN = 32;
+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));
+}
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+/**
+ * Read `Config.treasury` — the account every `register` call pays — given
+ * the `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ * shaped like a `Config` (too short to hold `treasury`).
+ */
+export async function fetchConfigTreasury(rpc, configAccount) {
+    const res = (await rpc("getAccountInfo", [
+        configAccount,
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const data = res?.value?.data?.[0];
+    if (!data)
+        return null;
+    const bin = atob(data);
+    if (bin.length < CONFIG_TREASURY_OFFSET + PUBKEY_LEN)
+        return null;
+    const raw = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        raw[i] = bin.charCodeAt(i);
+    return encodeBase58(raw.slice(CONFIG_TREASURY_OFFSET, CONFIG_TREASURY_OFFSET + PUBKEY_LEN));
+}
+/**
+ * Build `register`. Price is computed on-chain (see the module docs) — this
+ * builder does not know or assert it; simulate first if you need to show the
+ * payer a price before they sign.
+ */
+export function buildRegisterIx(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_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nameBytes.length, true);
+    data.set(nameBytes, 12);
+    data[12 + nameBytes.length] = p.handleType;
+    const hasIntegrator = p.integrator !== undefined || p.integratorAllowlist !== undefined;
+    if (hasIntegrator && (p.integrator === undefined || p.integratorAllowlist === undefined)) {
+        throw new Error("integrator and integratorAllowlist must both be supplied, or neither");
+    }
+    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 },
+    ];
+    if (hasIntegrator) {
+        keys.push({ pubkey: toBase58(p.integrator, "integrator"), isSigner: false, isWritable: true }, {
+            pubkey: toBase58(p.integratorAllowlist, "integratorAllowlist"),
+            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
+ *  write order in lib.rs) — lying after `treasury` (40) this module's own
+ *  {@link fetchConfigTreasury} already reads:
+ *    ...recovery_timelock_secs(i64)@256 lease_rate_divisor(u64)@264
+ *    lease_grace_period_secs(i64)@272 forti_mint(32)@280
+ *    forti_treasury_ata(32)@312 veforti_program(32)@344
+ *    forti_buyback_recipient(32)@376 forti_rate_per_lamport(u64)@408
+ *    veforti_bonus_bps(u16)@416 forti_buyback_share_bps(u16)@418 */
+const CONFIG_FORTI_MINT_OFFSET = 280;
+const CONFIG_FORTI_TREASURY_ATA_OFFSET = 312;
+const CONFIG_VEFORTI_PROGRAM_OFFSET = 344;
+const CONFIG_FORTI_BUYBACK_RECIPIENT_OFFSET = 376;
+const CONFIG_FORTI_RATE_OFFSET = 408;
+const CONFIG_FORTI_MIN_LEN = CONFIG_FORTI_RATE_OFFSET + 8;
+/** Read the `Config` fields a `register_with_forti` build needs, given the
+ *  `["config"]` PDA. Returns null if the account doesn't exist or isn't
+ *  shaped like a post-#8136 `Config` (too short to hold these fields —
+ *  e.g. a `Config` that hasn't run `migrate_config_v4` yet). */
+export async function fetchConfigForti(rpc, configAccount) {
+    const res = (await rpc("getAccountInfo", [
+        configAccount,
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const data = res?.value?.data?.[0];
+    if (!data)
+        return null;
+    const bin = atob(data);
+    if (bin.length < CONFIG_FORTI_MIN_LEN)
+        return null;
+    const raw = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        raw[i] = bin.charCodeAt(i);
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    return {
+        fortiMint: encodeBase58(raw.slice(CONFIG_FORTI_MINT_OFFSET, CONFIG_FORTI_MINT_OFFSET + PUBKEY_LEN)),
+        fortiTreasuryAta: encodeBase58(raw.slice(CONFIG_FORTI_TREASURY_ATA_OFFSET, CONFIG_FORTI_TREASURY_ATA_OFFSET + PUBKEY_LEN)),
+        veFortiProgram: encodeBase58(raw.slice(CONFIG_VEFORTI_PROGRAM_OFFSET, CONFIG_VEFORTI_PROGRAM_OFFSET + PUBKEY_LEN)),
+        fortiBuybackRecipient: encodeBase58(raw.slice(CONFIG_FORTI_BUYBACK_RECIPIENT_OFFSET, CONFIG_FORTI_BUYBACK_RECIPIENT_OFFSET + PUBKEY_LEN)),
+        fortiRatePerLamport: dv.getBigUint64(CONFIG_FORTI_RATE_OFFSET, true),
+    };
+}
+/**
+ * Build `register_with_forti` (#8136) — a SIBLING payment path to
+ * `register`, not a replacement. Price is computed on-chain the same way
+ * `register`'s is (see that builder's docs) — this builder does not know or
+ * assert it; use `/quote/:name?pay_with=forti[&payer=...]` (tools/api) or
+ * simulate first if you need to show the payer a price before they sign.
+ */
+export function buildRegisterWithFortiIx(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_WITH_FORTI_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.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.fortiMint, "fortiMint"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.payerFortiAccount, "payerFortiAccount"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.fortiTreasuryAta, "fortiTreasuryAta"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.fortiBuybackRecipient, "fortiBuybackRecipient"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.veFortiLock, "veFortiLock"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.tokenProgram, "tokenProgram"), isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/subname.d.ts

@@ -259,6 +259,11 @@ export declare function fetchSubnames(rpc: RpcFn, programId: string, parentHandl
  * 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[]>;
 /**

package/dist/subname.js

@@ -339,12 +339,17 @@ export async function fetchSubnames(rpc, programId, parentHandleAccount, parentR
  * 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);
+    return fetchRecords(rpc, programId, subnameAccount, subnameCreatedAt, 0n);
 }
 /**
  * Resolve a subname's LIVE address records — the ONLY safe entry point, both

package/dist/textRecords.d.ts

@@ -45,6 +45,14 @@
  * There is deliberately no way to decode or fetch a text record through
  * this module without the handle's `registered_at` in hand.
  *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer — text records too. The same functions therefore also
+ * demand the handle's `recordsClearedAt` (0 if never cleared, from
+ * `ParsedHandle`), and a text record is `stale` when EITHER
+ * `updated_at < registeredAt` OR `updated_at < recordsClearedAt`.
+ *
  * # These records count (#7384)
  *
  * `create_text_record` increments — and `close_text_record` decrements —
@@ -140,15 +148,17 @@ export declare function textValueToString(value: Uint8Array): string | null;
  *   value: Vec<u8> (u32 len + bytes, max 256)  updated_at: i64(8)  bump: u8(1)
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
- * caller from the Handle account — it decides `stale`. There is
- * intentionally no overload without it (see the module docs).
+ * caller from the Handle account — it decides `stale`. `recordsClearedAt` is
+ * that same Handle's `recordsClearedAt` (0 if never cleared, #8139), a
+ * SECOND independent staleness anchor. There is intentionally no overload
+ * without either (see the module docs).
  *
  * Returns null for anything that is not a TextRecord: wrong length, wrong
  * discriminator, lengths that do not fit, or a key that is not valid UTF-8
  * (the program's Borsh `String` guarantees it is, so that is not a
  * TextRecord).
  */
-export declare function decodeTextRecord(raw: Uint8Array, account: string, registeredAt: bigint): HandleTextRecord | null;
+export declare function decodeTextRecord(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: bigint): HandleTextRecord | null;
 /** The text records the CURRENT owner actually has — `stale` ones excluded.
  *  This is the list to render on a profile and count. */
 export declare function liveTextRecords(records: readonly HandleTextRecord[]): HandleTextRecord[];
@@ -162,12 +172,13 @@ export declare function liveTextRecords(records: readonly HandleTextRecord[]): H
  *
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
- * is no variant of this function without it. Every record is returned,
- * stale ones flagged, so an owner surface can show what a previous owner
- * left behind; anything that renders a profile takes
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Every record is returned, stale ones flagged, so an owner surface can show
+ * what a previous owner left behind; anything that renders a profile takes
  * {@link liveTextRecords}.
  */
-export declare function fetchTextRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint): Promise<HandleTextRecord[]>;
+export declare function fetchTextRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint): Promise<HandleTextRecord[]>;
 /** The delegate-aware trailing accounts every text-record builder shares —
  *  the exact rules of `delegate.ts`'s module docs. */
 interface RecordEditAuthorityParams {

package/dist/textRecords.js

@@ -45,6 +45,14 @@
  * There is deliberately no way to decode or fetch a text record through
  * this module without the handle's `registered_at` in hand.
  *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer — text records too. The same functions therefore also
+ * demand the handle's `recordsClearedAt` (0 if never cleared, from
+ * `ParsedHandle`), and a text record is `stale` when EITHER
+ * `updated_at < registeredAt` OR `updated_at < recordsClearedAt`.
+ *
  * # These records count (#7384)
  *
  * `create_text_record` increments — and `close_text_record` decrements —
@@ -164,15 +172,17 @@ export function textValueToString(value) {
  *   value: Vec<u8> (u32 len + bytes, max 256)  updated_at: i64(8)  bump: u8(1)
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
- * caller from the Handle account — it decides `stale`. There is
- * intentionally no overload without it (see the module docs).
+ * caller from the Handle account — it decides `stale`. `recordsClearedAt` is
+ * that same Handle's `recordsClearedAt` (0 if never cleared, #8139), a
+ * SECOND independent staleness anchor. There is intentionally no overload
+ * without either (see the module docs).
  *
  * Returns null for anything that is not a TextRecord: wrong length, wrong
  * discriminator, lengths that do not fit, or a key that is not valid UTF-8
  * (the program's Borsh `String` guarantees it is, so that is not a
  * TextRecord).
  */
-export function decodeTextRecord(raw, account, registeredAt) {
+export function decodeTextRecord(raw, account, registeredAt, recordsClearedAt) {
     if (raw.length !== TEXT_RECORD_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -207,7 +217,7 @@ export function decodeTextRecord(raw, account, registeredAt) {
         value,
         text: textValueToString(value),
         updatedAt,
-        stale: updatedAt < registeredAt,
+        stale: updatedAt < registeredAt || updatedAt < recordsClearedAt,
     };
 }
 /** The text records the CURRENT owner actually has — `stale` ones excluded.
@@ -225,12 +235,13 @@ export function liveTextRecords(records) {
  *
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
- * is no variant of this function without it. Every record is returned,
- * stale ones flagged, so an owner surface can show what a previous owner
- * left behind; anything that renders a profile takes
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Every record is returned, stale ones flagged, so an owner surface can show
+ * what a previous owner left behind; anything that renders a profile takes
  * {@link liveTextRecords}.
  */
-export async function fetchTextRecords(rpc, programId, handleAccount, registeredAt) {
+export async function fetchTextRecords(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -249,7 +260,7 @@ export async function fetchTextRecords(rpc, programId, handleAccount, registered
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const decoded = decodeTextRecord(raw, a.pubkey, registeredAt);
+        const decoded = decodeTextRecord(raw, a.pubkey, registeredAt, recordsClearedAt);
         // Defence in depth: the memcmp filter should guarantee the handle
         // match, but a wrong offset would silently attribute someone else's
         // record to this handle. A malformed account is skipped, not fatal.