@x1id/resolve 0.2.1 → 0.6.0

package/dist/recordWrite.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Write builders for the address `Record` family: `create_record` and the
+ * three `verify_record_*` proof-of-control instructions (ETH/secp256k1,
+ * SVM/ed25519, BTC/BIP-137). `records.ts` was read-only until now — every
+ * other record family (text records, attestations, vouchers, subnames...)
+ * already had write builders; this was the one gap (WP #8142).
+ *
+ * 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 `["record", handlePda, coinTypeLE(4)]`
+ * with your runtime's canonical `findProgramAddress`.
+ *
+ * # What this SDK does and does not do for you
+ *
+ * This does NOT sign anything, derive an address from a signature, or
+ * verify a signature client-side — that's the on-chain program's job
+ * (`verify_record_eth`/`svm`/`btc` recover the signer's address from the
+ * signature itself and compare it to the record's claimed value; a client
+ * proving nothing false cannot fabricate a match). What this module DOES do:
+ *
+ * 1. {@link buildRecordChallenge} — build the exact bytes a wallet must
+ *    sign, byte-identical to `handle-normalize`'s Rust `challenge()`
+ *    (verified: `crates/handle-normalize/src/challenge.rs`). Unlike the
+ *    off-chain control-proof flow (`control.ts`), this challenge's nonce
+ *    does NOT need to be server-issued — the on-chain transaction landing
+ *    IS the single-use event, so any ASCII-alphanumeric nonce (1..=64
+ *    chars) the caller picks is fine.
+ * 2. {@link splitEthSignature} / {@link splitBtcSignature} — repackage what
+ *    a wallet's `personal_sign` (ETH) or `signmessage` (BTC) actually
+ *    returns into the exact args each verify instruction expects.
+ * 3. The four instruction builders themselves.
+ *
+ * # ETH: EIP-191 `personal_sign`, not EIP-712
+ *
+ * `verify_record_eth` (lib.rs) hashes the challenge with EIP-191's
+ * `"\x19Ethereum Signed Message:\n" + len + message` framing — the exact
+ * framing every wallet's `personal_sign` / `eth_sign` RPC method produces.
+ * There is no EIP-712 typed-data variant on-chain to build a client for.
+ *
+ * # BTC: mainnet-only, compressed P2PKH or bech32/P2WPKH only
+ *
+ * `verify_record_btc` derives the address FROM the recovered pubkey (never
+ * trusts a client-supplied address) and only accepts the header-byte ranges
+ * for compressed P2PKH (31-34) and bech32/P2WPKH (39-42) — see `btc.rs`'s
+ * module doc for exactly why uncompressed P2PKH and P2SH-segwit are refused
+ * rather than guessed. {@link splitBtcSignature} passes the header byte
+ * through unchanged; it is the wallet's job to produce one of the two
+ * supported ranges (most current wallets do).
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+export declare const CREATE_RECORD_DISCRIMINATOR: Uint8Array;
+export declare const VERIFY_RECORD_ETH_DISCRIMINATOR: Uint8Array;
+export declare const VERIFY_RECORD_SVM_DISCRIMINATOR: Uint8Array;
+export declare const VERIFY_RECORD_BTC_DISCRIMINATOR: Uint8Array;
+/** The delegate-aware trailing account every verify builder shares — same
+ *  rule as `textRecords.ts`'s identically-named private helper (not shared
+ *  across files by import: each write-builder module owns its own copy,
+ *  matching this SDK's existing convention). */
+interface RecordEditAuthorityParams {
+    readonly recordDelegate?: AddressLike;
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * `x1-handles:v1:<handle>:<coinType>:<registeredAt>:<nonce>` — byte-identical
+ * to `handle_normalize::challenge` (Rust). `handle` must already be
+ * canonical (pass it through {@link import("./parse.js").normalizeHandle}
+ * first if it might have a leading `@` or mixed case).
+ */
+export declare function buildRecordChallenge(handle: string, coinType: number, registeredAt: bigint, nonce: string): string;
+/** Split a 65-byte ETH `personal_sign` output (`r(32) || s(32) || v(1)`)
+ *  into `verify_record_eth`'s `{signature: [u8;64], recoveryId: u8}`,
+ *  normalizing `v`'s two common conventions (27/28, matching most wallets'
+ *  raw RPC output, or already 0/1). */
+export declare function splitEthSignature(sig65: Uint8Array): {
+    signature: Uint8Array;
+    recoveryId: number;
+};
+/** Split a 65-byte BTC BIP-137 `signmessage` output (`header(1) || r(32) ||
+ *  s(32)`) into `verify_record_btc`'s `{header, signature: [u8;64]}`. The
+ *  header byte is passed through unchanged — see the module docs for which
+ *  ranges `verify_record_btc` accepts. */
+export declare function splitBtcSignature(sig65: Uint8Array): {
+    header: number;
+    signature: Uint8Array;
+};
+export interface CreateRecordParams {
+    readonly programId: AddressLike;
+    readonly payer: AddressLike;
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    /** The `["record", handle, coinTypeLE(4)]` PDA. */
+    readonly record: AddressLike;
+    readonly coinType: number;
+    /** Raw address bytes (1..=64), NOT verified yet — `verified` starts
+     *  false until a matching `verify_record_*` call succeeds. */
+    readonly value: Uint8Array;
+}
+export declare function buildCreateRecordIx(p: CreateRecordParams): BuiltInstruction;
+export interface VerifyRecordEthParams extends RecordEditAuthorityParams {
+    readonly programId: AddressLike;
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    readonly record: AddressLike;
+    readonly nonce: string;
+    /** The 64-byte `r || s` half — use {@link splitEthSignature} on a
+     *  wallet's raw 65-byte `personal_sign` output. */
+    readonly signature: Uint8Array;
+    readonly recoveryId: number;
+}
+export declare function buildVerifyRecordEthIx(p: VerifyRecordEthParams): BuiltInstruction;
+export interface VerifyRecordSvmParams extends RecordEditAuthorityParams {
+    readonly programId: AddressLike;
+    readonly owner: AddressLike;
+    /** The address being claimed — MUST co-sign this transaction; its
+     *  signature IS the proof, no challenge/nonce needed (X1 and Solana
+     *  share ed25519). */
+    readonly claimed: AddressLike;
+    readonly handle: AddressLike;
+    readonly record: AddressLike;
+}
+export declare function buildVerifyRecordSvmIx(p: VerifyRecordSvmParams): BuiltInstruction;
+export interface VerifyRecordBtcParams extends RecordEditAuthorityParams {
+    readonly programId: AddressLike;
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    readonly record: AddressLike;
+    readonly nonce: string;
+    /** BIP-137 header byte — use {@link splitBtcSignature} on a wallet's raw
+     *  65-byte `signmessage` output. Only 31-34 (compressed P2PKH) and 39-42
+     *  (bech32/P2WPKH) are accepted on-chain; see the module docs. */
+    readonly header: number;
+    /** The 64-byte `r || s` half. */
+    readonly signature: Uint8Array;
+}
+export declare function buildVerifyRecordBtcIx(p: VerifyRecordBtcParams): BuiltInstruction;
+export {};

package/dist/recordWrite.js

@@ -0,0 +1,228 @@
+/**
+ * Write builders for the address `Record` family: `create_record` and the
+ * three `verify_record_*` proof-of-control instructions (ETH/secp256k1,
+ * SVM/ed25519, BTC/BIP-137). `records.ts` was read-only until now — every
+ * other record family (text records, attestations, vouchers, subnames...)
+ * already had write builders; this was the one gap (WP #8142).
+ *
+ * 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 `["record", handlePda, coinTypeLE(4)]`
+ * with your runtime's canonical `findProgramAddress`.
+ *
+ * # What this SDK does and does not do for you
+ *
+ * This does NOT sign anything, derive an address from a signature, or
+ * verify a signature client-side — that's the on-chain program's job
+ * (`verify_record_eth`/`svm`/`btc` recover the signer's address from the
+ * signature itself and compare it to the record's claimed value; a client
+ * proving nothing false cannot fabricate a match). What this module DOES do:
+ *
+ * 1. {@link buildRecordChallenge} — build the exact bytes a wallet must
+ *    sign, byte-identical to `handle-normalize`'s Rust `challenge()`
+ *    (verified: `crates/handle-normalize/src/challenge.rs`). Unlike the
+ *    off-chain control-proof flow (`control.ts`), this challenge's nonce
+ *    does NOT need to be server-issued — the on-chain transaction landing
+ *    IS the single-use event, so any ASCII-alphanumeric nonce (1..=64
+ *    chars) the caller picks is fine.
+ * 2. {@link splitEthSignature} / {@link splitBtcSignature} — repackage what
+ *    a wallet's `personal_sign` (ETH) or `signmessage` (BTC) actually
+ *    returns into the exact args each verify instruction expects.
+ * 3. The four instruction builders themselves.
+ *
+ * # ETH: EIP-191 `personal_sign`, not EIP-712
+ *
+ * `verify_record_eth` (lib.rs) hashes the challenge with EIP-191's
+ * `"\x19Ethereum Signed Message:\n" + len + message` framing — the exact
+ * framing every wallet's `personal_sign` / `eth_sign` RPC method produces.
+ * There is no EIP-712 typed-data variant on-chain to build a client for.
+ *
+ * # BTC: mainnet-only, compressed P2PKH or bech32/P2WPKH only
+ *
+ * `verify_record_btc` derives the address FROM the recovered pubkey (never
+ * trusts a client-supplied address) and only accepts the header-byte ranges
+ * for compressed P2PKH (31-34) and bech32/P2WPKH (39-42) — see `btc.rs`'s
+ * module doc for exactly why uncompressed P2PKH and P2SH-segwit are refused
+ * rather than guessed. {@link splitBtcSignature} passes the header byte
+ * through unchanged; it is the wallet's job to produce one of the two
+ * supported ranges (most current wallets do).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { recordDelegateNonePlaceholder, recordDelegateSomeSlot } from "./delegate.js";
+import { normalizeHandle } from "./parse.js";
+import { ResolveError } from "./types.js";
+/** Matches `control.ts`'s identically-named private helper: STRICT
+ *  canonical-form check (reject, never silently transform), mirroring the
+ *  Rust `is_canonical` the challenge builder must match exactly —
+ *  `normalizeHandle` alone would accept `"@Alice"` by transforming it,
+ *  which `handle_normalize::challenge` (Rust) does NOT: it demands
+ *  already-canonical input and rejects anything else outright. */
+function isCanonicalHandle(handle) {
+    try {
+        return normalizeHandle(handle) === handle;
+    }
+    catch {
+        return false;
+    }
+}
+export const CREATE_RECORD_DISCRIMINATOR = Uint8Array.from([
+    116, 124, 63, 58, 126, 204, 178, 10,
+]);
+export const VERIFY_RECORD_ETH_DISCRIMINATOR = Uint8Array.from([
+    57, 157, 98, 0, 160, 210, 94, 234,
+]);
+export const VERIFY_RECORD_SVM_DISCRIMINATOR = Uint8Array.from([
+    234, 151, 82, 212, 185, 112, 234, 212,
+]);
+export const VERIFY_RECORD_BTC_DISCRIMINATOR = Uint8Array.from([
+    54, 50, 183, 232, 122, 200, 194, 64,
+]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const NONCE_RE = /^[0-9A-Za-z]{1,64}$/;
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+function encVec(bytes) {
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+function encString(s) {
+    return encVec(new TextEncoder().encode(s));
+}
+function pushAuthorityTail(keys, programId, p) {
+    if (p.recordDelegate !== undefined) {
+        keys.push(recordDelegateSomeSlot(p.recordDelegate));
+    }
+    else if (p.holderTokenAccount !== undefined) {
+        keys.push(recordDelegateNonePlaceholder(programId));
+    }
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+}
+// ---------------------------------------------------------------------------
+// Challenge
+// ---------------------------------------------------------------------------
+/**
+ * `x1-handles:v1:<handle>:<coinType>:<registeredAt>:<nonce>` — byte-identical
+ * to `handle_normalize::challenge` (Rust). `handle` must already be
+ * canonical (pass it through {@link import("./parse.js").normalizeHandle}
+ * first if it might have a leading `@` or mixed case).
+ */
+export function buildRecordChallenge(handle, coinType, registeredAt, nonce) {
+    if (!isCanonicalHandle(handle)) {
+        throw new ResolveError("invalid-handle", `"${handle}" is not a canonical handle`, handle);
+    }
+    if (!NONCE_RE.test(nonce)) {
+        throw new Error("nonce must be 1..=64 ASCII alphanumeric characters");
+    }
+    return `x1-handles:v1:${handle}:${coinType}:${registeredAt}:${nonce}`;
+}
+/** Split a 65-byte ETH `personal_sign` output (`r(32) || s(32) || v(1)`)
+ *  into `verify_record_eth`'s `{signature: [u8;64], recoveryId: u8}`,
+ *  normalizing `v`'s two common conventions (27/28, matching most wallets'
+ *  raw RPC output, or already 0/1). */
+export function splitEthSignature(sig65) {
+    if (sig65.length !== 65)
+        throw new Error("ETH signature must be exactly 65 bytes (r || s || v)");
+    const v = sig65[64];
+    const recoveryId = v >= 27 ? v - 27 : v;
+    if (recoveryId !== 0 && recoveryId !== 1) {
+        throw new Error(`unrecognized recovery id byte: ${v}`);
+    }
+    return { signature: sig65.slice(0, 64), recoveryId };
+}
+/** Split a 65-byte BTC BIP-137 `signmessage` output (`header(1) || r(32) ||
+ *  s(32)`) into `verify_record_btc`'s `{header, signature: [u8;64]}`. The
+ *  header byte is passed through unchanged — see the module docs for which
+ *  ranges `verify_record_btc` accepts. */
+export function splitBtcSignature(sig65) {
+    if (sig65.length !== 65)
+        throw new Error("BTC signature must be exactly 65 bytes (header || r || s)");
+    return { header: sig65[0], signature: sig65.slice(1) };
+}
+export function buildCreateRecordIx(p) {
+    if (p.value.length === 0 || p.value.length > 64) {
+        throw new Error("value must be 1..=64 bytes");
+    }
+    const coinTypeBytes = new Uint8Array(4);
+    new DataView(coinTypeBytes.buffer).setUint32(0, p.coinType, true);
+    const data = new Uint8Array(8 + 4 + 4 + p.value.length);
+    data.set(CREATE_RECORD_DISCRIMINATOR, 0);
+    data.set(coinTypeBytes, 8);
+    data.set(encVec(p.value), 12);
+    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.record, "record"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+export function buildVerifyRecordEthIx(p) {
+    if (p.signature.length !== 64)
+        throw new Error("signature must be exactly 64 bytes (r || s)");
+    if (p.recoveryId !== 0 && p.recoveryId !== 1)
+        throw new Error("recoveryId must be 0 or 1");
+    if (!NONCE_RE.test(p.nonce))
+        throw new Error("nonce must be 1..=64 ASCII alphanumeric characters");
+    const nonceEnc = encString(p.nonce);
+    const data = new Uint8Array(8 + nonceEnc.length + 64 + 1);
+    data.set(VERIFY_RECORD_ETH_DISCRIMINATOR, 0);
+    data.set(nonceEnc, 8);
+    data.set(p.signature, 8 + nonceEnc.length);
+    data[8 + nonceEnc.length + 64] = p.recoveryId;
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+export function buildVerifyRecordSvmIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.claimed, "claimed"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data: VERIFY_RECORD_SVM_DISCRIMINATOR.slice() };
+}
+export function buildVerifyRecordBtcIx(p) {
+    if (p.signature.length !== 64)
+        throw new Error("signature must be exactly 64 bytes (r || s)");
+    if (!Number.isInteger(p.header) || p.header < 0 || p.header > 255) {
+        throw new Error("header must be a single byte (0-255)");
+    }
+    if (!NONCE_RE.test(p.nonce))
+        throw new Error("nonce must be 1..=64 ASCII alphanumeric characters");
+    const nonceEnc = encString(p.nonce);
+    const data = new Uint8Array(8 + nonceEnc.length + 65);
+    data.set(VERIFY_RECORD_BTC_DISCRIMINATOR, 0);
+    data.set(nonceEnc, 8);
+    data[8 + nonceEnc.length] = p.header;
+    data.set(p.signature, 8 + nonceEnc.length + 1);
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.record, "record"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/records.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Per-chain payment records (`Record` accounts) — read WITH the universal
+ * staleness rule from docs/record-trust.md structurally enforced.
+ *
+ * # Why every function here demands `registeredAt`
+ *
+ * A `Handle`'s address is `["handle", name]` — a pure function of the name.
+ * Release + re-register lands the new registration at the SAME pubkey, and
+ * `Record` PDAs (`["record", handle_pubkey, coin_type]`) hang off that pubkey,
+ * so a record a PREVIOUS owner created (possibly `verified: true` for THEIR
+ * address) is physically attached to the new owner's name with no action by
+ * anyone. The program cannot prevent this (state.rs, `Handle` doc comment);
+ * the mandatory read-side rule is:
+ *
+ *     record.updated_at >= handle.registered_at
+ *
+ * A record that fails it belongs to a previous, unrelated owner and must be
+ * treated as unset/unverified — for PAYMENT resolution, not just badges.
+ * 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";
+/** `8 + Record::INIT_SPACE` — the program allocates the full 64-byte `value`
+ *  capacity, so every Record account is exactly this long:
+ *  8 + 32 + 4 + (4 + 64) + 1 + 8 + 1. */
+export declare const RECORD_LEN = 122;
+/** `sha256("account:Record")[..8]`, hex — the tag every Record account's
+ *  data starts with. Pinned (this SDK is zero-dependency and cannot assume
+ *  WebCrypto SHA-256 everywhere it runs); the value is asserted against a
+ *  re-derivation in the test suite so a typo can never silently pass. */
+export declare const RECORD_DISC = "fee975fc4ca6928b";
+/** Reverse of CHAIN_COIN_TYPE — which chain a stored coin_type belongs to, or
+ *  null for a coin_type this SDK does not know how to render. */
+export declare function chainForCoinType(coinType: number): Chain | null;
+/** A decoded per-chain payment record, staleness already judged. */
+export interface HandleRecord {
+    /** The Record account's address, base58. */
+    readonly account: string;
+    /** The Handle account this record hangs off, base58. */
+    readonly handle: string;
+    readonly coinType: number;
+    /** Which chain `coinType` maps to, or null for an unknown coin type. */
+    readonly chain: Chain | null;
+    /** Raw bytes as stored on-chain. */
+    readonly value: Uint8Array;
+    /** Human-readable address string — see `valueToAddress`. */
+    readonly address: string;
+    /**
+     * `Record.verified` AS STORED, gated by the staleness rule: `false`
+     * whenever the record is `stale`, whatever the account says. A stale
+     * `true` is a proof a PREVIOUS owner made; it is never surfaced as a
+     * verification of the current owner's address.
+     */
+    readonly verified: boolean;
+    /** `Record.updated_at`, unix seconds. */
+    readonly updatedAt: bigint;
+    /**
+     * The rule docs/record-trust.md mandates: this record is only the current
+     * owner's if `updated_at >= handle.registered_at`. A stale record belongs
+     * to a previous, unrelated owner of the same name: it must never be
+     * resolved as this name's address, never counted, and only ever offered
+     * to the CURRENT owner as something to remove.
+     */
+    readonly stale: boolean;
+}
+/**
+ * Decode one Record account.
+ *
+ * Record account layout, after the 8-byte Anchor discriminator:
+ *
+ *   handle: Pubkey(32)  coin_type: u32(4)  value: Vec<u8> (u32 len + bytes, max 64)
+ *   verified: bool(1)  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` (and so `verified`).
+ * `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 /
+ * Auction PDAs of the same handle also carry the handle pubkey at offset 8,
+ * 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, 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[];
+/**
+ * Render stored record bytes for display / payment, per the conventions
+ * app/src/lib/x1/records.ts writes them with: X1/SOL are 32-byte pubkeys
+ * (base58), ETH is 20 raw bytes (0x-hex), BTC is the UTF-8 bytes of the
+ * canonical address string. Unknown coin types render as hex so a value is
+ * never silently hidden.
+ */
+export declare function valueToAddress(chain: Chain | null, value: Uint8Array): string;
+/**
+ * Fetch every Record account of a handle — one `getProgramAccounts` call,
+ * filtered by the RPC on size (122), the Record discriminator at offset 0
+ * and the handle pubkey at offset 8, then every byte re-checked locally
+ * (the node's filters are an optimisation, never the guarantee). Scoping the
+ * scan to the registry program id also IS the ownership check: a foreign
+ * account cannot appear in it.
+ *
+ * `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. `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, recordsClearedAt: bigint): Promise<HandleRecord[]>;