@x1id/resolve 0.2.1 → 0.6.0

package/dist/lock.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Name locks (#7377): decode helpers for the on-chain lock state, plus the
+ * instruction builders for `lock_handle` and the timelocked unlock flow
+ * (`initiate_unlock` / `complete_unlock` / `cancel_unlock`).
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return the
+ * transport-neutral {@link BuiltInstruction} `delegate.ts` uses; adapt to
+ * web3.js exactly as that module's header documents.
+ *
+ * # The lock extension, mirrored from state.rs's EXTENSION OFFSET REGISTRY
+ *
+ * A `Handle` account's struct is frozen at 157 bytes (`8 + INIT_SPACE`);
+ * features append fixed-offset raw regions past it:
+ *
+ *   offset  size  region
+ *   157     33    NFT capability extension (presence tag + mint pubkey)
+ *   190      1    RESERVED, permanently-unused gap (#7377 — see below)
+ *   191      5    record_count: presence tag + u32 LE live-record count
+ *   196      9    lock: locked(u8) + unlock_initiated_at(i64 LE)   ← this module
+ *   205      —    next free offset
+ *
+ * The lock region lives at 196, PAST record_count — NOT at the byte 190 that
+ * was originally reserved for it. The shipped feature needs 9 bytes (a flag
+ * plus an `unlock_initiated_at` timestamp for the timelocked unlock), which
+ * does not fit in one byte, and record_count (191–195) is deployed with live
+ * data whose offset cannot move. Byte 190 stays a documented, zeroed gap.
+ *
+ * # No presence tag — unlocked and uninitialized are the same value
+ *
+ * Unlike record_count (whose `0` count is distinct from "uninitialized"), the
+ * lock uses NO presence byte: `locked === 0` — which is also what a short or
+ * never-locked account reads as — IS the unlocked state. So {@link readLock}
+ * is total: a pre-lock handle (account too short) and a zeroed flag both read
+ * as `false` (unlocked), never an error and never a wrong answer.
+ *
+ * # The wire rules the on-chain program enforces (mirror of lib.rs)
+ *
+ * - All four instructions are gated by the STRICT authority check
+ *   (`require_current_authority` in lib.rs): the untokenized owner, OR —
+ *   for a TOKENIZED handle — the current NFT holder, who appends their ATA for
+ *   the handle's NFT mint as the first extra (remaining) account
+ *   ({@link LockParams.holderTokenAccount} etc.).
+ * - `lock_handle` refuses if a live `Listing` (`HandleListedCannotLock`, 6053)
+ *   or `Auction` (`AuctionLive`, 6031) exists — a lock and an active market are
+ *   mutually exclusive. It grows the handle account through the lock region on
+ *   first lock (paid by `payer`), so `payer` must be a writable signer.
+ * - HARD LOCK: while locked, NOTHING about the handle can change. All 23
+ *   mutating instructions refuse with `HandleLocked` (6049) — the 11
+ *   name-MOVING ones (`transfer`, `release_handle`, `list_handle`, `buy_handle`,
+ *   `accept_offer`, `start_auction`, `settle_auction`, `mint_handle_nft`,
+ *   `set_recovery`, `initiate_recovery`, `complete_recovery`) AND the 12
+ *   record/primary/text/delegate editors (`create_record`, `update_record`,
+ *   `verify_record_eth`/`svm`/`btc`, `close_record`, `create_text_record`,
+ *   `update_text_record`, `close_text_record`, `set_record_delegate`,
+ *   `revoke_record_delegate`, `set_primary`) — so a stolen key cannot redirect a
+ *   locked handle's addresses. Only `cancel_recovery` and `clear_primary` stay
+ *   available (the compromised-key owner can still cancel an attacker's
+ *   recovery; `clear_primary` cannot encumber the handle).
+ * - Unlock is timelocked: `initiate_unlock` stamps the clock (refused if not
+ *   locked, `HandleNotLocked` 6050); `complete_unlock` clears the lock only
+ *   after `Config.recovery_timelock_secs` has elapsed (`UnlockNotInitiated`
+ *   6051 / `UnlockTimelockNotElapsed` 6052); `cancel_unlock` clears a pending
+ *   unlock but KEEPS the lock — the owner's defence against a stolen-key thief.
+ * - `lock_handle` is idempotent: re-locking re-asserts the flag and clears any
+ *   pending unlock (same effect as `cancel_unlock`).
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** Byte offset of the lock extension: base(157) + NFT ext(33) + reserved gap
+ *  byte(1) + record_count ext(5) = 196. */
+export declare const LOCK_EXT_OFFSET = 196;
+/** `locked: u8` (1) + `unlock_initiated_at: i64` LE (8). */
+export declare const LOCK_EXT_LEN = 9;
+/** Hard floor (seconds) on the UNLOCK timelock, mirrored from the program's
+ *  `MIN_UNLOCK_TIMELOCK_SECS`. `complete_unlock` enforces
+ *  `max(Config.recovery_timelock_secs, MIN_UNLOCK_TIMELOCK_SECS)`, so no config
+ *  value can collapse the reaction window. A UI computing when an unlock becomes
+ *  available MUST apply the same clamp — see {@link unlockAvailableAt}. */
+export declare const MIN_UNLOCK_TIMELOCK_SECS: number;
+/**
+ * The unix timestamp at which a pending `complete_unlock` becomes valid, given
+ * the handle's `unlock_initiated_at` and the config's `recovery_timelock_secs`.
+ * Applies the same `MIN_UNLOCK_TIMELOCK_SECS` floor the program enforces, so a
+ * UI never shows an ETA earlier than the program will actually allow. Returns
+ * `null` when no unlock is pending (`unlockInitiatedAt == 0n`).
+ */
+export declare function unlockAvailableAt(unlockInitiatedAt: bigint, recoveryTimelockSecs: bigint): bigint | null;
+/** Anchor instruction discriminators — `sha256("global:<name>")[0..8]`,
+ *  pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
+ *  everywhere it runs) and asserted against a re-derivation in the test suite
+ *  so a typo can never silently pass. */
+export declare const LOCK_HANDLE_DISCRIMINATOR: Uint8Array;
+export declare const INITIATE_UNLOCK_DISCRIMINATOR: Uint8Array;
+export declare const COMPLETE_UNLOCK_DISCRIMINATOR: Uint8Array;
+export declare const CANCEL_UNLOCK_DISCRIMINATOR: Uint8Array;
+/** The decoded lock state of a `Handle` account. */
+export interface LockState {
+    /** Whether the handle is locked — every name-moving instruction refuses. */
+    readonly locked: boolean;
+    /** Unix timestamp of a pending `initiate_unlock` (`0n` when none is pending).
+     *  Meaningful only while `locked`; `complete_unlock` can land once
+     *  `Config.recovery_timelock_secs` has elapsed since this. */
+    readonly unlockInitiatedAt: bigint;
+}
+/**
+ * Read the lock flag from a `Handle` account's raw data (exactly what an RPC
+ * `getAccountInfo` returns for the `["handle", name]` PDA). Mirrors the
+ * program's `Handle::read_lock` tolerance exactly: a short account (a handle
+ * registered or grown before the lock region existed) and a zeroed flag both
+ * read as `false` (unlocked) — never an error, never a wrong answer.
+ */
+export declare function readLock(data: Uint8Array): boolean;
+/**
+ * Read the pending-unlock timestamp (`0n` == none pending). Tolerant exactly
+ * like {@link readLock}: a region too short to hold the i64 reads as `0n`.
+ * Meaningful only while {@link readLock} is `true`.
+ */
+export declare function readUnlockInitiatedAt(data: Uint8Array): bigint;
+/**
+ * Decode the full lock state ({@link readLock} + {@link readUnlockInitiatedAt})
+ * from a `Handle` account's raw data.
+ */
+export declare function readLockState(data: Uint8Array): LockState;
+export interface LockParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the one-time account grow through the lock region on first lock.
+     *  Signer, writable. */
+    readonly payer: AddressLike;
+    /** The handle's CURRENT authority (untokenized owner, or NFT holder).
+     *  Signer. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** The `["listing", handle]` PDA — must NOT exist (mutual exclusion). Derive
+     *  per `delegate.ts`'s module docs. */
+    readonly listing: AddressLike;
+    /** The `["auction", handle]` PDA — must NOT exist (mutual exclusion). */
+    readonly auction: AddressLike;
+    /** TOKENIZED handles only: the holder's associated token account for the
+     *  handle's NFT mint, appended as the strict check's remaining-account proof.
+     *  Omit for an untokenized handle. */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `lock_handle` — freeze every name-moving instruction until a
+ * timelocked unlock. Idempotent (re-locking clears any pending unlock).
+ */
+export declare function buildLockHandleIx(p: LockParams): BuiltInstruction;
+export interface UnlockParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's CURRENT authority (untokenized owner, or NFT holder).
+     *  Signer. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** TOKENIZED handles only — same rule as {@link LockParams.holderTokenAccount}. */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `initiate_unlock` — begin the timelocked unlock (stamps the clock;
+ * unlocks nothing yet). Refused if the handle is not locked.
+ */
+export declare function buildInitiateUnlockIx(p: UnlockParams): BuiltInstruction;
+/**
+ * Build `cancel_unlock` — cancel a pending unlock but LEAVE the handle locked
+ * (the owner's defence against a stolen-key thief who called `initiate_unlock`).
+ */
+export declare function buildCancelUnlockIx(p: UnlockParams): BuiltInstruction;
+export interface CompleteUnlockParams extends UnlockParams {
+    /** The `["config"]` PDA — the handler reads `recovery_timelock_secs` from it
+     *  (reused as the unlock timelock). */
+    readonly config: AddressLike;
+}
+/**
+ * Build `complete_unlock` — finish the timelocked unlock: clears the lock once
+ * `Config.recovery_timelock_secs` has elapsed since `initiate_unlock`.
+ */
+export declare function buildCompleteUnlockIx(p: CompleteUnlockParams): BuiltInstruction;

package/dist/lock.js

@@ -0,0 +1,211 @@
+/**
+ * Name locks (#7377): decode helpers for the on-chain lock state, plus the
+ * instruction builders for `lock_handle` and the timelocked unlock flow
+ * (`initiate_unlock` / `complete_unlock` / `cancel_unlock`).
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return the
+ * transport-neutral {@link BuiltInstruction} `delegate.ts` uses; adapt to
+ * web3.js exactly as that module's header documents.
+ *
+ * # The lock extension, mirrored from state.rs's EXTENSION OFFSET REGISTRY
+ *
+ * A `Handle` account's struct is frozen at 157 bytes (`8 + INIT_SPACE`);
+ * features append fixed-offset raw regions past it:
+ *
+ *   offset  size  region
+ *   157     33    NFT capability extension (presence tag + mint pubkey)
+ *   190      1    RESERVED, permanently-unused gap (#7377 — see below)
+ *   191      5    record_count: presence tag + u32 LE live-record count
+ *   196      9    lock: locked(u8) + unlock_initiated_at(i64 LE)   ← this module
+ *   205      —    next free offset
+ *
+ * The lock region lives at 196, PAST record_count — NOT at the byte 190 that
+ * was originally reserved for it. The shipped feature needs 9 bytes (a flag
+ * plus an `unlock_initiated_at` timestamp for the timelocked unlock), which
+ * does not fit in one byte, and record_count (191–195) is deployed with live
+ * data whose offset cannot move. Byte 190 stays a documented, zeroed gap.
+ *
+ * # No presence tag — unlocked and uninitialized are the same value
+ *
+ * Unlike record_count (whose `0` count is distinct from "uninitialized"), the
+ * lock uses NO presence byte: `locked === 0` — which is also what a short or
+ * never-locked account reads as — IS the unlocked state. So {@link readLock}
+ * is total: a pre-lock handle (account too short) and a zeroed flag both read
+ * as `false` (unlocked), never an error and never a wrong answer.
+ *
+ * # The wire rules the on-chain program enforces (mirror of lib.rs)
+ *
+ * - All four instructions are gated by the STRICT authority check
+ *   (`require_current_authority` in lib.rs): the untokenized owner, OR —
+ *   for a TOKENIZED handle — the current NFT holder, who appends their ATA for
+ *   the handle's NFT mint as the first extra (remaining) account
+ *   ({@link LockParams.holderTokenAccount} etc.).
+ * - `lock_handle` refuses if a live `Listing` (`HandleListedCannotLock`, 6053)
+ *   or `Auction` (`AuctionLive`, 6031) exists — a lock and an active market are
+ *   mutually exclusive. It grows the handle account through the lock region on
+ *   first lock (paid by `payer`), so `payer` must be a writable signer.
+ * - HARD LOCK: while locked, NOTHING about the handle can change. All 23
+ *   mutating instructions refuse with `HandleLocked` (6049) — the 11
+ *   name-MOVING ones (`transfer`, `release_handle`, `list_handle`, `buy_handle`,
+ *   `accept_offer`, `start_auction`, `settle_auction`, `mint_handle_nft`,
+ *   `set_recovery`, `initiate_recovery`, `complete_recovery`) AND the 12
+ *   record/primary/text/delegate editors (`create_record`, `update_record`,
+ *   `verify_record_eth`/`svm`/`btc`, `close_record`, `create_text_record`,
+ *   `update_text_record`, `close_text_record`, `set_record_delegate`,
+ *   `revoke_record_delegate`, `set_primary`) — so a stolen key cannot redirect a
+ *   locked handle's addresses. Only `cancel_recovery` and `clear_primary` stay
+ *   available (the compromised-key owner can still cancel an attacker's
+ *   recovery; `clear_primary` cannot encumber the handle).
+ * - Unlock is timelocked: `initiate_unlock` stamps the clock (refused if not
+ *   locked, `HandleNotLocked` 6050); `complete_unlock` clears the lock only
+ *   after `Config.recovery_timelock_secs` has elapsed (`UnlockNotInitiated`
+ *   6051 / `UnlockTimelockNotElapsed` 6052); `cancel_unlock` clears a pending
+ *   unlock but KEEPS the lock — the owner's defence against a stolen-key thief.
+ * - `lock_handle` is idempotent: re-locking re-asserts the flag and clears any
+ *   pending unlock (same effect as `cancel_unlock`).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Byte offset of the lock extension: base(157) + NFT ext(33) + reserved gap
+ *  byte(1) + record_count ext(5) = 196. */
+export const LOCK_EXT_OFFSET = 196;
+/** `locked: u8` (1) + `unlock_initiated_at: i64` LE (8). */
+export const LOCK_EXT_LEN = 9;
+/** Hard floor (seconds) on the UNLOCK timelock, mirrored from the program's
+ *  `MIN_UNLOCK_TIMELOCK_SECS`. `complete_unlock` enforces
+ *  `max(Config.recovery_timelock_secs, MIN_UNLOCK_TIMELOCK_SECS)`, so no config
+ *  value can collapse the reaction window. A UI computing when an unlock becomes
+ *  available MUST apply the same clamp — see {@link unlockAvailableAt}. */
+export const MIN_UNLOCK_TIMELOCK_SECS = 24 * 60 * 60;
+/**
+ * The unix timestamp at which a pending `complete_unlock` becomes valid, given
+ * the handle's `unlock_initiated_at` and the config's `recovery_timelock_secs`.
+ * Applies the same `MIN_UNLOCK_TIMELOCK_SECS` floor the program enforces, so a
+ * UI never shows an ETA earlier than the program will actually allow. Returns
+ * `null` when no unlock is pending (`unlockInitiatedAt == 0n`).
+ */
+export function unlockAvailableAt(unlockInitiatedAt, recoveryTimelockSecs) {
+    if (unlockInitiatedAt === 0n)
+        return null;
+    const floor = BigInt(MIN_UNLOCK_TIMELOCK_SECS);
+    const timelock = recoveryTimelockSecs > floor ? recoveryTimelockSecs : floor;
+    return unlockInitiatedAt + timelock;
+}
+/** Anchor instruction discriminators — `sha256("global:<name>")[0..8]`,
+ *  pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
+ *  everywhere it runs) and asserted against a re-derivation in the test suite
+ *  so a typo can never silently pass. */
+export const LOCK_HANDLE_DISCRIMINATOR = Uint8Array.from([
+    104, 51, 234, 115, 96, 138, 171, 223,
+]);
+export const INITIATE_UNLOCK_DISCRIMINATOR = Uint8Array.from([
+    41, 118, 177, 198, 27, 237, 231, 69,
+]);
+export const COMPLETE_UNLOCK_DISCRIMINATOR = Uint8Array.from([
+    22, 203, 15, 189, 239, 125, 25, 132,
+]);
+export const CANCEL_UNLOCK_DISCRIMINATOR = Uint8Array.from([
+    116, 58, 36, 132, 24, 104, 170, 228,
+]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBase58(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return encodeBase58(b);
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return encodeBase58(v);
+}
+/**
+ * Read the lock flag from a `Handle` account's raw data (exactly what an RPC
+ * `getAccountInfo` returns for the `["handle", name]` PDA). Mirrors the
+ * program's `Handle::read_lock` tolerance exactly: a short account (a handle
+ * registered or grown before the lock region existed) and a zeroed flag both
+ * read as `false` (unlocked) — never an error, never a wrong answer.
+ */
+export function readLock(data) {
+    if (data.length < LOCK_EXT_OFFSET + 1)
+        return false;
+    return data[LOCK_EXT_OFFSET] !== 0;
+}
+/**
+ * Read the pending-unlock timestamp (`0n` == none pending). Tolerant exactly
+ * like {@link readLock}: a region too short to hold the i64 reads as `0n`.
+ * Meaningful only while {@link readLock} is `true`.
+ */
+export function readUnlockInitiatedAt(data) {
+    const start = LOCK_EXT_OFFSET + 1;
+    if (data.length < start + 8)
+        return 0n;
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(start, true);
+}
+/**
+ * Decode the full lock state ({@link readLock} + {@link readUnlockInitiatedAt})
+ * from a `Handle` account's raw data.
+ */
+export function readLockState(data) {
+    return { locked: readLock(data), unlockInitiatedAt: readUnlockInitiatedAt(data) };
+}
+/**
+ * Build `lock_handle` — freeze every name-moving instruction until a
+ * timelocked unlock. Idempotent (re-locking clears any pending unlock).
+ */
+export function buildLockHandleIx(p) {
+    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: true },
+        { pubkey: toBase58(p.listing, "listing"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.auction, "auction"), isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data: LOCK_HANDLE_DISCRIMINATOR.slice() };
+}
+/** Shared builder for the two `UnlockHandle`-context instructions
+ *  (`initiate_unlock`, `cancel_unlock`): identical account list, different
+ *  discriminator. */
+function buildUnlockHandleIx(disc, p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data: disc.slice() };
+}
+/**
+ * Build `initiate_unlock` — begin the timelocked unlock (stamps the clock;
+ * unlocks nothing yet). Refused if the handle is not locked.
+ */
+export function buildInitiateUnlockIx(p) {
+    return buildUnlockHandleIx(INITIATE_UNLOCK_DISCRIMINATOR, p);
+}
+/**
+ * Build `cancel_unlock` — cancel a pending unlock but LEAVE the handle locked
+ * (the owner's defence against a stolen-key thief who called `initiate_unlock`).
+ */
+export function buildCancelUnlockIx(p) {
+    return buildUnlockHandleIx(CANCEL_UNLOCK_DISCRIMINATOR, p);
+}
+/**
+ * Build `complete_unlock` — finish the timelocked unlock: clears the lock once
+ * `Config.recovery_timelock_secs` has elapsed since `initiate_unlock`.
+ */
+export function buildCompleteUnlockIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data: COMPLETE_UNLOCK_DISCRIMINATOR.slice() };
+}

package/dist/recordCount.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The record_count Handle extension (#7384): decode helper for the on-chain
+ * live-record counter, plus the instruction builder for the admin-only
+ * `backfill_record_count` migration path.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). The builder returns
+ * the same transport-neutral {@link BuiltInstruction} `delegate.ts` uses.
+ *
+ * # The extension, mirrored from state.rs's EXTENSION OFFSET REGISTRY
+ *
+ * A `Handle` account's struct is frozen at 157 bytes (`8 + INIT_SPACE`);
+ * features append fixed-offset raw regions past it:
+ *
+ *   offset  size  region
+ *   157     33    NFT capability extension (presence tag + mint pubkey)
+ *   190      1    RESERVED lock byte (#7377, unbuilt)
+ *   191      5    record_count: presence tag + u32 LE live-record count
+ *   196      —    next free offset
+ *
+ * `create_record` increments the count (initializing the extension and
+ * growing the account on first use — which is why the record-editing
+ * create/close instructions pass the HANDLE account WRITABLE as of this
+ * feature; the account LIST is unchanged), `close_record` decrements it
+ * (saturating, only when initialized), and `release_handle` refuses while an
+ * initialized count is nonzero (`HandleHasRecords`, code 6044).
+ *
+ * # Uninitialized is NOT zero
+ *
+ * {@link readRecordCount} returns `null` for a handle whose extension is
+ * uninitialized — an account too short (a pre-#7384 handle) or a presence
+ * byte still zero (grown for the NFT extension, never counted). Such a
+ * handle keeps the OLD unguarded release behaviour until the admin stamps it
+ * via `backfill_record_count` or a post-upgrade `create_record` initializes
+ * it. A `0` return, by contrast, is an initialized, trustworthy
+ * "provably no live records". Never conflate the two: rendering `null` as
+ * "0 records" would tell an owner their release is safe when the program
+ * cannot actually vouch for that.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** `8 + Handle::INIT_SPACE` — the frozen base struct size, and the first
+ *  extension offset. */
+export declare const HANDLE_BASE_LEN = 157;
+/** Byte offset of the record_count extension: base(157) + NFT ext(33) +
+ *  reserved lock byte(1). */
+export declare const RECORD_COUNT_EXT_OFFSET = 191;
+/** presence tag(1) + u32 LE count(4). */
+export declare const RECORD_COUNT_EXT_LEN = 5;
+/** One past the last known extension region (must match the program's
+ *  `Handle::KNOWN_EXT_END`) — the size a fully-grown Handle account has under
+ *  this program version. Layout: base(157) + NFT(33) + reserved(1) +
+ *  record_count(5) + lock(9) = 205. Was 196 (pre-lock); the #7377 lock extension
+ *  (see LOCK_EXT_OFFSET=196 / LOCK_EXT_LEN=9 in lock.ts) pushed it to 205, so any
+ *  consumer allocating/resizing to this constant must use the current value. */
+export declare const HANDLE_KNOWN_EXT_END = 205;
+/** Anchor instruction discriminator:
+ *  `sha256("global:backfill_record_count")[0..8]`. Pinned (this SDK is
+ *  zero-dependency and cannot assume WebCrypto SHA-256 everywhere it runs);
+ *  asserted against a re-derivation in the test suite so a typo can never
+ *  silently pass. */
+export declare const BACKFILL_RECORD_COUNT_DISCRIMINATOR: Uint8Array;
+/**
+ * Read the live-record count from a `Handle` account's raw data (exactly
+ * what an RPC `getAccountInfo` returns for the `["handle", name]` PDA).
+ *
+ * Returns the count when the extension is INITIALIZED, and `null` when it is
+ * not — see the module docs for why `null` and `0` mean different things and
+ * must be rendered differently. Mirrors the program's
+ * `Handle::read_record_count` tolerance exactly: a short account and a
+ * zeroed region are both `null`, never an error.
+ */
+export declare function readRecordCount(data: Uint8Array): number | null;
+export interface BackfillRecordCountParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The registry admin (`Config.admin`). Signer; also pays the one-time
+     *  account grow when the target handle's extension region isn't allocated
+     *  yet. */
+    readonly admin: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The `["handle", name]` PDA being stamped. */
+    readonly handle: AddressLike;
+    /** The true live-record count, computed OFF-chain — a `getProgramAccounts`
+     *  scan filtered on the handle pubkey (what `fetchRecords` runs; count the
+     *  full list, stale records included, since stale records are still live
+     *  accounts that block a clean release). Overwrites whatever is stored —
+     *  the instruction is deliberately idempotent/re-runnable. */
+    readonly count: number;
+}
+/**
+ * Build `backfill_record_count` — admin-only: stamp a pre-#7384 handle's
+ * record_count extension with the off-chain-computed truth, moving it
+ * permanently out of the unguarded-release window. Mainnet never needs it
+ * (the mainnet registry starts fresh at cutover, counted from the first
+ * record); this is testnet migration + permanent correction tooling.
+ */
+export declare function buildBackfillRecordCountIx(p: BackfillRecordCountParams): BuiltInstruction;

package/dist/recordCount.js

@@ -0,0 +1,114 @@
+/**
+ * The record_count Handle extension (#7384): decode helper for the on-chain
+ * live-record counter, plus the instruction builder for the admin-only
+ * `backfill_record_count` migration path.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). The builder returns
+ * the same transport-neutral {@link BuiltInstruction} `delegate.ts` uses.
+ *
+ * # The extension, mirrored from state.rs's EXTENSION OFFSET REGISTRY
+ *
+ * A `Handle` account's struct is frozen at 157 bytes (`8 + INIT_SPACE`);
+ * features append fixed-offset raw regions past it:
+ *
+ *   offset  size  region
+ *   157     33    NFT capability extension (presence tag + mint pubkey)
+ *   190      1    RESERVED lock byte (#7377, unbuilt)
+ *   191      5    record_count: presence tag + u32 LE live-record count
+ *   196      —    next free offset
+ *
+ * `create_record` increments the count (initializing the extension and
+ * growing the account on first use — which is why the record-editing
+ * create/close instructions pass the HANDLE account WRITABLE as of this
+ * feature; the account LIST is unchanged), `close_record` decrements it
+ * (saturating, only when initialized), and `release_handle` refuses while an
+ * initialized count is nonzero (`HandleHasRecords`, code 6044).
+ *
+ * # Uninitialized is NOT zero
+ *
+ * {@link readRecordCount} returns `null` for a handle whose extension is
+ * uninitialized — an account too short (a pre-#7384 handle) or a presence
+ * byte still zero (grown for the NFT extension, never counted). Such a
+ * handle keeps the OLD unguarded release behaviour until the admin stamps it
+ * via `backfill_record_count` or a post-upgrade `create_record` initializes
+ * it. A `0` return, by contrast, is an initialized, trustworthy
+ * "provably no live records". Never conflate the two: rendering `null` as
+ * "0 records" would tell an owner their release is safe when the program
+ * cannot actually vouch for that.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** `8 + Handle::INIT_SPACE` — the frozen base struct size, and the first
+ *  extension offset. */
+export const HANDLE_BASE_LEN = 157;
+/** Byte offset of the record_count extension: base(157) + NFT ext(33) +
+ *  reserved lock byte(1). */
+export const RECORD_COUNT_EXT_OFFSET = 191;
+/** presence tag(1) + u32 LE count(4). */
+export const RECORD_COUNT_EXT_LEN = 5;
+/** One past the last known extension region (must match the program's
+ *  `Handle::KNOWN_EXT_END`) — the size a fully-grown Handle account has under
+ *  this program version. Layout: base(157) + NFT(33) + reserved(1) +
+ *  record_count(5) + lock(9) = 205. Was 196 (pre-lock); the #7377 lock extension
+ *  (see LOCK_EXT_OFFSET=196 / LOCK_EXT_LEN=9 in lock.ts) pushed it to 205, so any
+ *  consumer allocating/resizing to this constant must use the current value. */
+export const HANDLE_KNOWN_EXT_END = 205;
+/** Anchor instruction discriminator:
+ *  `sha256("global:backfill_record_count")[0..8]`. Pinned (this SDK is
+ *  zero-dependency and cannot assume WebCrypto SHA-256 everywhere it runs);
+ *  asserted against a re-derivation in the test suite so a typo can never
+ *  silently pass. */
+export const BACKFILL_RECORD_COUNT_DISCRIMINATOR = Uint8Array.from([
+    151, 122, 233, 167, 188, 54, 32, 110,
+]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBase58(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return encodeBase58(b);
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return encodeBase58(v);
+}
+/**
+ * Read the live-record count from a `Handle` account's raw data (exactly
+ * what an RPC `getAccountInfo` returns for the `["handle", name]` PDA).
+ *
+ * Returns the count when the extension is INITIALIZED, and `null` when it is
+ * not — see the module docs for why `null` and `0` mean different things and
+ * must be rendered differently. Mirrors the program's
+ * `Handle::read_record_count` tolerance exactly: a short account and a
+ * zeroed region are both `null`, never an error.
+ */
+export function readRecordCount(data) {
+    if (data.length < RECORD_COUNT_EXT_OFFSET + RECORD_COUNT_EXT_LEN)
+        return null;
+    if (data[RECORD_COUNT_EXT_OFFSET] === 0)
+        return null;
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(RECORD_COUNT_EXT_OFFSET + 1, true);
+}
+/**
+ * Build `backfill_record_count` — admin-only: stamp a pre-#7384 handle's
+ * record_count extension with the off-chain-computed truth, moving it
+ * permanently out of the unguarded-release window. Mainnet never needs it
+ * (the mainnet registry starts fresh at cutover, counted from the first
+ * record); this is testnet migration + permanent correction tooling.
+ */
+export function buildBackfillRecordCountIx(p) {
+    if (!Number.isInteger(p.count) || p.count < 0 || p.count > 0xffffffff) {
+        throw new Error("count must be a u32");
+    }
+    const data = new Uint8Array(8 + 4);
+    data.set(BACKFILL_RECORD_COUNT_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, p.count, true);
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}