@x1id/resolve 0.22.0 → 0.43.0

package/dist/payment.d.ts

@@ -5,8 +5,15 @@
  * A handle's per-chain address `Record` can be written by a record-editing
  * DELEGATE, not just the owner — so an UNVERIFIED record must never receive
  * money: a malicious delegate could silently redirect payments. On-chain
- * VERIFICATION (`verify_record_svm` — the recorded address itself co-signed)
- * is the guard, so the rule every pay surface shares is:
+ * VERIFICATION is the guard: `verify_record_svm`/`_eth`/`_btc` need the
+ * recorded address's own proof (co-signature / signed challenge) AND the
+ * handle's CURRENT AUTHORITY (owner, or pNFT holder) as the signer. A
+ * delegate cannot verify (`DelegateCannotVerify`, 6137, Sentinel
+ * x1p-007-04), and every delegate write leaves the record unverified, so a
+ * delegate alone can never produce a record this rule pays. (Before that
+ * program upgrade a delegate COULD verify a key it controlled; a record a
+ * delegate verified before the upgrade stays verified until the owner
+ * updates, clears or re-verifies it.) The rule every pay surface shares is:
  *
  *   1. a LIVE, VERIFIED record for the payment chain → that record's address
  *      (`basis: "verified-record"`). Staleness is judged first: a record from

package/dist/payment.js

@@ -5,8 +5,15 @@
  * A handle's per-chain address `Record` can be written by a record-editing
  * DELEGATE, not just the owner — so an UNVERIFIED record must never receive
  * money: a malicious delegate could silently redirect payments. On-chain
- * VERIFICATION (`verify_record_svm` — the recorded address itself co-signed)
- * is the guard, so the rule every pay surface shares is:
+ * VERIFICATION is the guard: `verify_record_svm`/`_eth`/`_btc` need the
+ * recorded address's own proof (co-signature / signed challenge) AND the
+ * handle's CURRENT AUTHORITY (owner, or pNFT holder) as the signer. A
+ * delegate cannot verify (`DelegateCannotVerify`, 6137, Sentinel
+ * x1p-007-04), and every delegate write leaves the record unverified, so a
+ * delegate alone can never produce a record this rule pays. (Before that
+ * program upgrade a delegate COULD verify a key it controlled; a record a
+ * delegate verified before the upgrade stays verified until the owner
+ * updates, clears or re-verifies it.) The rule every pay surface shares is:
  *
  *   1. a LIVE, VERIFIED record for the payment chain → that record's address
  *      (`basis: "verified-record"`). Staleness is judged first: a record from

package/dist/recovery.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Social recovery (Recovery 2, WP 8868): instruction builders for the four
+ * recovery instructions and a state reader with time remaining.
+ *
+ *   set_recovery(Option<Pubkey>)  owner      — set / clear the recovery key;
+ *                                              also CLEARS any pending recovery
+ *   initiate_recovery(target)     recovery   — start the timelock toward `target`
+ *   cancel_recovery               owner      — stop a pending recovery (allowed
+ *                                              even while the name is locked)
+ *   complete_recovery             recovery   — once the timelock elapsed, owner
+ *                                              becomes the target
+ *
+ * The lock family (`lock_handle`, `initiate_unlock`, `cancel_unlock`,
+ * `complete_unlock`) already lives in `lock.ts`; {@link fetchRecoveryState}
+ * reports both, because a lock also freezes `set_recovery` /
+ * `initiate_recovery` / `complete_recovery`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. Builders return the transport-neutral
+ * {@link BuiltInstruction} (`delegate.ts`); PDAs come from an injected
+ * {@link PdaFinder} (`namespacePricing.ts`).
+ *
+ * # Wire rules mirrored from programs/x1-handles/src/lib.rs
+ *
+ * - `OwnerOnly { owner: Signer, handle: mut (has_one = owner) }` backs
+ *   `set_recovery` / `cancel_recovery`; `Recover { recovery: Signer,
+ *   handle: mut, config, auction }` backs `initiate_recovery` /
+ *   `complete_recovery` (the `auction` PDA `["auction", handle]` is checked
+ *   for a live bid; it need not exist).
+ * - The WHOLE family is refused on a TOKENIZED handle (`HandleIsTokenized`),
+ *   and scoped `name.tld` handles are always tokenized — so no remaining
+ *   accounts are ever needed (the bare PDA check never reads them).
+ * - `complete_recovery` requires `now - recovery_initiated_at >=
+ *   max(Config.recovery_timelock_secs, MIN_RECOVERY_TIMELOCK_SECS)`; a lock
+ *   (`HandleLocked`) or a bid-carrying auction (`AuctionHasBids`) also refuse
+ *   it, and `initiate_recovery`.
+ * - Completion KEEPS the recovery key (audit L-1); every other ownership
+ *   change clears it.
+ */
+import { type RpcFn } from "./accounts.js";
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { PdaFinder } from "./namespacePricing.js";
+/** Anchor discriminators, `sha256("global:<name>")[0..8]`, pinned and
+ *  re-derived in the test suite. */
+export declare const SET_RECOVERY_DISCRIMINATOR: Uint8Array;
+export declare const INITIATE_RECOVERY_DISCRIMINATOR: Uint8Array;
+export declare const CANCEL_RECOVERY_DISCRIMINATOR: Uint8Array;
+export declare const COMPLETE_RECOVERY_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:Handle")[0..8]` / `sha256("account:Config")[0..8]`. */
+export declare const HANDLE_ACCOUNT_DISCRIMINATOR: Uint8Array;
+export declare const CONFIG_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** lib.rs `RECOVERY_TIMELOCK_SECS` — the default `Config.recovery_timelock_secs`. */
+export declare const DEFAULT_RECOVERY_TIMELOCK_SECS: number;
+/** lib.rs `MIN_RECOVERY_TIMELOCK_SECS` — `complete_recovery`'s hard floor. */
+export declare const MIN_RECOVERY_TIMELOCK_SECS: number;
+/** `Config.recovery_timelock_secs` (i64 LE) offset: disc(8) admin(32)
+ *  treasury(32) launch_ts(8) tiers(80) nft_tiers(80) total_handles_sold(8)
+ *  nfts_minted(8) = 256. Present on a V2+ Config (>= 265 bytes). */
+export declare const CONFIG_RECOVERY_TIMELOCK_OFFSET = 256;
+/** `["config"]` and `["auction", handle]` — the two extra accounts `Recover`
+ *  needs. */
+export declare function deriveRecoveryAccounts(find: PdaFinder, programId: AddressLike, handle: AddressLike): Promise<{
+    readonly config: string;
+    readonly auction: string;
+}>;
+export interface SetRecoveryParams {
+    readonly programId: AddressLike;
+    /** The handle's owner. Signer. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** The new recovery key, or `null` to clear it. Setting (or clearing) the
+     *  key also cancels any pending recovery. */
+    readonly recovery: AddressLike | null;
+}
+/** `set_recovery(Option<Pubkey>)` — data: disc ‖ 0 | (1 ‖ pubkey). */
+export declare function buildSetRecoveryIx(p: SetRecoveryParams): BuiltInstruction;
+export interface CancelRecoveryParams {
+    readonly programId: AddressLike;
+    /** The handle's owner. Signer. */
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+}
+/** `cancel_recovery` — the owner stops a pending recovery. Data: disc only. */
+export declare function buildCancelRecoveryIx(p: CancelRecoveryParams): BuiltInstruction;
+export interface RecoverParams {
+    readonly programId: AddressLike;
+    /** The configured recovery key (`Handle.recovery`). Signer. */
+    readonly recovery: AddressLike;
+    readonly handle: AddressLike;
+    /** The `["config"]` PDA ({@link deriveRecoveryAccounts}). */
+    readonly config: AddressLike;
+    /** The `["auction", handle]` PDA — passed even when no auction exists. */
+    readonly auction: AddressLike;
+}
+export interface InitiateRecoveryParams extends RecoverParams {
+    /** Who will own the handle once the recovery completes. */
+    readonly target: AddressLike;
+}
+/** `initiate_recovery(target)` — data: disc ‖ target(32). Starts the timelock;
+ *  the owner can cancel until {@link RecoveryState.pending}`.completesAt`. */
+export declare function buildInitiateRecoveryIx(p: InitiateRecoveryParams): BuiltInstruction;
+/** `complete_recovery` — data: disc only. Valid once the timelock elapsed
+ *  ({@link RecoveryState.pending}`.completable`). */
+export declare function buildCompleteRecoveryIx(p: RecoverParams): BuiltInstruction;
+/** The recovery fields of a `Handle` account. */
+export interface HandleRecoveryFields {
+    readonly owner: string;
+    /** The configured recovery key, or null. */
+    readonly recovery: string | null;
+    /** Unix seconds; 0n = no recovery pending. */
+    readonly recoveryInitiatedAt: bigint;
+    readonly recoveryTarget: string | null;
+    readonly registeredAt: bigint;
+    readonly tokenized: boolean;
+}
+/**
+ * Decode the recovery fields of a `Handle` account's raw data (sequential:
+ * the two `Option<Pubkey>` fields shift what follows them). Null when the
+ * data is not a Handle (wrong discriminator / too short).
+ *
+ *   disc(8) name(32) name_len(1) owner(32)@41 handle_type(1)
+ *   recovery: Option<Pubkey>  recovery_initiated_at: i64
+ *   recovery_target: Option<Pubkey>  registered_at: i64  bump(1)
+ *   [157: nft tag(1) mint(32)]
+ */
+export declare function decodeHandleRecovery(data: Uint8Array): HandleRecoveryFields | null;
+/** `Config.recovery_timelock_secs`, or null for a pre-V2 Config / not a Config. */
+export declare function readConfigRecoveryTimelock(data: Uint8Array): bigint | null;
+/** The timelock `complete_recovery` enforces: `max(config ?? default, floor)`. */
+export declare function effectiveRecoveryTimelock(configSecs: bigint | null): bigint;
+/** When a pending recovery can complete (null = none pending). Same clamp as
+ *  the program, so a UI never shows an ETA earlier than it will allow. */
+export declare function recoveryCompletesAt(recoveryInitiatedAt: bigint, configSecs: bigint | null): bigint | null;
+export interface RecoveryState {
+    readonly handle: string;
+    readonly owner: string;
+    /** Recovery is refused on chain for a tokenized handle. */
+    readonly tokenized: boolean;
+    readonly recoveryKey: string | null;
+    /** `!tokenized && !locked && recoveryKey !== null`: initiate is possible. */
+    readonly recoveryAvailable: boolean;
+    readonly pending: {
+        readonly target: string | null;
+        readonly initiatedAt: bigint;
+        readonly completesAt: bigint;
+        /** Seconds until `complete_recovery` can land (0n once it can). */
+        readonly secondsRemaining: bigint;
+        /** Timelock elapsed AND not locked. A live bid-carrying auction would
+         *  still refuse it (`AuctionHasBids`). */
+        readonly completable: boolean;
+    } | null;
+    readonly locked: boolean;
+    readonly pendingUnlock: {
+        readonly initiatedAt: bigint;
+        readonly unlocksAt: bigint;
+        readonly secondsRemaining: bigint;
+        readonly completable: boolean;
+    } | null;
+    /** The effective timelock (seconds) in force now. */
+    readonly timelockSecs: bigint;
+    readonly nowSecs: bigint;
+}
+/** Pure: the state from raw Handle data + the Config timelock + now. */
+export declare function computeRecoveryState(handle: AddressLike, handleData: Uint8Array, configTimelockSecs: bigint | null, nowSecs: bigint): RecoveryState | null;
+export interface FetchRecoveryStateOptions {
+    readonly programId: AddressLike;
+    /** The `["handle", name]` PDA (derive it with the resolver's WASM
+     *  `deriveHandleAccount`, or `makeScopedHandleDeriver` for name.tld). */
+    readonly handle: AddressLike;
+    /** The `["config"]` PDA; or pass `find` to derive it. */
+    readonly config?: AddressLike;
+    readonly find?: PdaFinder;
+    /** Unix seconds; defaults to the local clock. Pass the cluster time
+     *  (`getBlockTime`) when it matters to the second. */
+    readonly nowSecs?: bigint;
+    readonly commitment?: string;
+}
+/**
+ * Read a handle's recovery + lock state from chain (the authority — the
+ * indexer's `GET /recovery` is a convenience view): the Handle account and
+ * the Config timelock, in two `getAccountInfo` calls. Null when the handle
+ * does not exist. Throws when the account exists but is not a registry
+ * Handle.
+ */
+export declare function fetchRecoveryState(rpc: RpcFn, opts: FetchRecoveryStateOptions): Promise<RecoveryState | null>;

package/dist/recovery.js

@@ -0,0 +1,276 @@
+/**
+ * Social recovery (Recovery 2, WP 8868): instruction builders for the four
+ * recovery instructions and a state reader with time remaining.
+ *
+ *   set_recovery(Option<Pubkey>)  owner      — set / clear the recovery key;
+ *                                              also CLEARS any pending recovery
+ *   initiate_recovery(target)     recovery   — start the timelock toward `target`
+ *   cancel_recovery               owner      — stop a pending recovery (allowed
+ *                                              even while the name is locked)
+ *   complete_recovery             recovery   — once the timelock elapsed, owner
+ *                                              becomes the target
+ *
+ * The lock family (`lock_handle`, `initiate_unlock`, `cancel_unlock`,
+ * `complete_unlock`) already lives in `lock.ts`; {@link fetchRecoveryState}
+ * reports both, because a lock also freezes `set_recovery` /
+ * `initiate_recovery` / `complete_recovery`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. Builders return the transport-neutral
+ * {@link BuiltInstruction} (`delegate.ts`); PDAs come from an injected
+ * {@link PdaFinder} (`namespacePricing.ts`).
+ *
+ * # Wire rules mirrored from programs/x1-handles/src/lib.rs
+ *
+ * - `OwnerOnly { owner: Signer, handle: mut (has_one = owner) }` backs
+ *   `set_recovery` / `cancel_recovery`; `Recover { recovery: Signer,
+ *   handle: mut, config, auction }` backs `initiate_recovery` /
+ *   `complete_recovery` (the `auction` PDA `["auction", handle]` is checked
+ *   for a live bid; it need not exist).
+ * - The WHOLE family is refused on a TOKENIZED handle (`HandleIsTokenized`),
+ *   and scoped `name.tld` handles are always tokenized — so no remaining
+ *   accounts are ever needed (the bare PDA check never reads them).
+ * - `complete_recovery` requires `now - recovery_initiated_at >=
+ *   max(Config.recovery_timelock_secs, MIN_RECOVERY_TIMELOCK_SECS)`; a lock
+ *   (`HandleLocked`) or a bid-carrying auction (`AuctionHasBids`) also refuse
+ *   it, and `initiate_recovery`.
+ * - Completion KEEPS the recovery key (audit L-1); every other ownership
+ *   change clears it.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { bytesEqual, parseHandleAccount } from "./accounts.js";
+import { readLockState, unlockAvailableAt } from "./lock.js";
+/** Anchor discriminators, `sha256("global:<name>")[0..8]`, pinned and
+ *  re-derived in the test suite. */
+export const SET_RECOVERY_DISCRIMINATOR = Uint8Array.from([70, 35, 195, 148, 6, 140, 128, 124]);
+export const INITIATE_RECOVERY_DISCRIMINATOR = Uint8Array.from([132, 148, 60, 74, 49, 178, 235, 187]);
+export const CANCEL_RECOVERY_DISCRIMINATOR = Uint8Array.from([176, 23, 203, 37, 121, 251, 227, 83]);
+export const COMPLETE_RECOVERY_DISCRIMINATOR = Uint8Array.from([195, 236, 5, 5, 131, 32, 196, 110]);
+/** `sha256("account:Handle")[0..8]` / `sha256("account:Config")[0..8]`. */
+export const HANDLE_ACCOUNT_DISCRIMINATOR = Uint8Array.from([150, 96, 143, 54, 64, 147, 63, 63]);
+export const CONFIG_ACCOUNT_DISCRIMINATOR = Uint8Array.from([155, 12, 170, 224, 30, 250, 204, 130]);
+/** lib.rs `RECOVERY_TIMELOCK_SECS` — the default `Config.recovery_timelock_secs`. */
+export const DEFAULT_RECOVERY_TIMELOCK_SECS = 7 * 24 * 60 * 60;
+/** lib.rs `MIN_RECOVERY_TIMELOCK_SECS` — `complete_recovery`'s hard floor. */
+export const MIN_RECOVERY_TIMELOCK_SECS = 24 * 60 * 60;
+/** `Config.recovery_timelock_secs` (i64 LE) offset: disc(8) admin(32)
+ *  treasury(32) launch_ts(8) tiers(80) nft_tiers(80) total_handles_sold(8)
+ *  nfts_minted(8) = 256. Present on a V2+ Config (>= 265 bytes). */
+export const CONFIG_RECOVERY_TIMELOCK_OFFSET = 256;
+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);
+}
+function toBytes(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 concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// PDAs
+// ---------------------------------------------------------------------------
+const TE = new TextEncoder();
+/** `["config"]` and `["auction", handle]` — the two extra accounts `Recover`
+ *  needs. */
+export async function deriveRecoveryAccounts(find, programId, handle) {
+    const program = toBase58(programId, "programId");
+    const [config, auction] = await Promise.all([
+        find([TE.encode("config")], program),
+        find([TE.encode("auction"), toBytes(handle, "handle")], program),
+    ]);
+    return { config, auction };
+}
+/** `set_recovery(Option<Pubkey>)` — data: disc ‖ 0 | (1 ‖ pubkey). */
+export function buildSetRecoveryIx(p) {
+    const arg = p.recovery === null ? Uint8Array.of(0) : concat(Uint8Array.of(1), toBytes(p.recovery, "recovery"));
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+            { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        ],
+        data: concat(SET_RECOVERY_DISCRIMINATOR, arg),
+    };
+}
+/** `cancel_recovery` — the owner stops a pending recovery. Data: disc only. */
+export function buildCancelRecoveryIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+            { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        ],
+        data: CANCEL_RECOVERY_DISCRIMINATOR.slice(),
+    };
+}
+function recoverKeys(p) {
+    return [
+        { pubkey: toBase58(p.recovery, "recovery"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.auction, "auction"), isSigner: false, isWritable: false },
+    ];
+}
+/** `initiate_recovery(target)` — data: disc ‖ target(32). Starts the timelock;
+ *  the owner can cancel until {@link RecoveryState.pending}`.completesAt`. */
+export function buildInitiateRecoveryIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: recoverKeys(p),
+        data: concat(INITIATE_RECOVERY_DISCRIMINATOR, toBytes(p.target, "target")),
+    };
+}
+/** `complete_recovery` — data: disc only. Valid once the timelock elapsed
+ *  ({@link RecoveryState.pending}`.completable`). */
+export function buildCompleteRecoveryIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: recoverKeys(p),
+        data: COMPLETE_RECOVERY_DISCRIMINATOR.slice(),
+    };
+}
+/**
+ * Decode the recovery fields of a `Handle` account's raw data (sequential:
+ * the two `Option<Pubkey>` fields shift what follows them). Null when the
+ * data is not a Handle (wrong discriminator / too short).
+ *
+ *   disc(8) name(32) name_len(1) owner(32)@41 handle_type(1)
+ *   recovery: Option<Pubkey>  recovery_initiated_at: i64
+ *   recovery_target: Option<Pubkey>  registered_at: i64  bump(1)
+ *   [157: nft tag(1) mint(32)]
+ */
+export function decodeHandleRecovery(data) {
+    if (data.length < 8 || !bytesEqual(data.subarray(0, 8), HANDLE_ACCOUNT_DISCRIMINATOR))
+        return null;
+    // The ONE sequential Handle decoder (accounts.ts) — never a second offset guess.
+    const h = parseHandleAccount(data);
+    if (!h)
+        return null;
+    return {
+        owner: encodeBase58(h.owner),
+        recovery: h.recovery ? encodeBase58(h.recovery) : null,
+        recoveryInitiatedAt: h.recoveryInitiatedAt,
+        recoveryTarget: h.recoveryTarget ? encodeBase58(h.recoveryTarget) : null,
+        registeredAt: h.registeredAt,
+        tokenized: h.nftMint !== null,
+    };
+}
+/** `Config.recovery_timelock_secs`, or null for a pre-V2 Config / not a Config. */
+export function readConfigRecoveryTimelock(data) {
+    if (!bytesEqual(data.subarray(0, 8), CONFIG_ACCOUNT_DISCRIMINATOR))
+        return null;
+    if (data.length < CONFIG_RECOVERY_TIMELOCK_OFFSET + 9)
+        return null;
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(CONFIG_RECOVERY_TIMELOCK_OFFSET, true);
+}
+/** The timelock `complete_recovery` enforces: `max(config ?? default, floor)`. */
+export function effectiveRecoveryTimelock(configSecs) {
+    const v = configSecs ?? BigInt(DEFAULT_RECOVERY_TIMELOCK_SECS);
+    const floor = BigInt(MIN_RECOVERY_TIMELOCK_SECS);
+    return v > floor ? v : floor;
+}
+/** When a pending recovery can complete (null = none pending). Same clamp as
+ *  the program, so a UI never shows an ETA earlier than it will allow. */
+export function recoveryCompletesAt(recoveryInitiatedAt, configSecs) {
+    if (recoveryInitiatedAt === 0n)
+        return null;
+    return recoveryInitiatedAt + effectiveRecoveryTimelock(configSecs);
+}
+/** Pure: the state from raw Handle data + the Config timelock + now. */
+export function computeRecoveryState(handle, handleData, configTimelockSecs, nowSecs) {
+    const f = decodeHandleRecovery(handleData);
+    if (!f)
+        return null;
+    const lock = readLockState(handleData);
+    const timelock = effectiveRecoveryTimelock(configTimelockSecs);
+    const completesAt = recoveryCompletesAt(f.recoveryInitiatedAt, configTimelockSecs);
+    // The unlock floor (lock.ts MIN_UNLOCK_TIMELOCK_SECS) equals the recovery
+    // floor today; use lock.ts's own helper so they can never drift apart.
+    const unlocksAt = lock.locked ? unlockAvailableAt(lock.unlockInitiatedAt, configTimelockSecs ?? BigInt(DEFAULT_RECOVERY_TIMELOCK_SECS)) : null;
+    const left = (t) => (t > nowSecs ? t - nowSecs : 0n);
+    return {
+        handle: toBase58(handle, "handle"),
+        owner: f.owner,
+        tokenized: f.tokenized,
+        recoveryKey: f.recovery,
+        recoveryAvailable: !f.tokenized && !lock.locked && f.recovery !== null,
+        pending: completesAt === null
+            ? null
+            : {
+                target: f.recoveryTarget,
+                initiatedAt: f.recoveryInitiatedAt,
+                completesAt,
+                secondsRemaining: left(completesAt),
+                completable: nowSecs >= completesAt && !lock.locked && !f.tokenized,
+            },
+        locked: lock.locked,
+        pendingUnlock: unlocksAt === null
+            ? null
+            : { initiatedAt: lock.unlockInitiatedAt, unlocksAt, secondsRemaining: left(unlocksAt), completable: nowSecs >= unlocksAt },
+        timelockSecs: timelock,
+        nowSecs,
+    };
+}
+async function readAccount(rpc, address, commitment) {
+    const res = (await rpc("getAccountInfo", [address, { encoding: "base64", commitment }]));
+    const v = res?.value;
+    if (!v)
+        return null;
+    const bin = atob(v.data[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    return { data, owner: v.owner };
+}
+/**
+ * Read a handle's recovery + lock state from chain (the authority — the
+ * indexer's `GET /recovery` is a convenience view): the Handle account and
+ * the Config timelock, in two `getAccountInfo` calls. Null when the handle
+ * does not exist. Throws when the account exists but is not a registry
+ * Handle.
+ */
+export async function fetchRecoveryState(rpc, opts) {
+    const programId = toBase58(opts.programId, "programId");
+    const handle = toBase58(opts.handle, "handle");
+    let config;
+    if (opts.config !== undefined)
+        config = toBase58(opts.config, "config");
+    else if (opts.find)
+        config = await opts.find([TE.encode("config")], programId);
+    else
+        throw new Error("fetchRecoveryState needs `config` or `find`");
+    const commitment = opts.commitment ?? "confirmed";
+    const [h, c] = await Promise.all([readAccount(rpc, handle, commitment), readAccount(rpc, config, commitment)]);
+    if (!h)
+        return null;
+    if (h.owner !== programId)
+        throw new Error("handle account is not owned by the registry program");
+    const timelock = c && c.owner === programId ? readConfigRecoveryTimelock(c.data) : null;
+    const now = opts.nowSecs ?? BigInt(Math.floor(Date.now() / 1000));
+    const s = computeRecoveryState(handle, h.data, timelock, now);
+    if (!s)
+        throw new Error("account is not an x1id Handle");
+    return s;
+}