@x1id/resolve 0.3.0 → 0.6.0

package/dist/attestation.js

@@ -50,6 +50,15 @@
  * documented blind spot is shared with `Handle.owner`/`Primary`/
  * `RecordDelegate`: a bearer-NFT marketplace trade bumps no epoch, so the
  * attestation keeps reading live until the attestor re-reviews or revokes.)
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer — its own doc comment (lib.rs) names attestations
+ * explicitly alongside records/text-records as sharing this epoch rule. The
+ * same functions therefore also demand the handle's `recordsClearedAt` (0 if
+ * never cleared, from `ParsedHandle`), and an attestation is `stale` when
+ * EITHER `attested_at < registeredAt` OR `attested_at < recordsClearedAt`.
  */
 import { encodeBase58 } from "./base58.js";
 import { decodeBase58_32 } from "./base58.js";
@@ -123,13 +132,15 @@ export function attestationKindName(kind) {
  * Decode one Attestation account.
  *
  * `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 an Attestation: wrong length or
  * wrong discriminator.
  */
-export function decodeAttestation(raw, account, registeredAt) {
+export function decodeAttestation(raw, account, registeredAt, recordsClearedAt) {
     if (raw.length !== ATTESTATION_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -155,7 +166,7 @@ export function decodeAttestation(raw, account, registeredAt) {
         evidenceHash,
         attestedAt,
         attestor,
-        stale: attestedAt < registeredAt,
+        stale: attestedAt < registeredAt || attestedAt < recordsClearedAt,
     };
 }
 /** The attestations that vouch for the CURRENT owner — `stale` ones
@@ -181,12 +192,13 @@ export function isHandleVerified(attestations) {
  *
  * `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 attestation is returned,
- * stale ones flagged, so an owner surface can show what a previous
- * registration left behind; anything that renders a verified badge takes
- * {@link isHandleVerified} / {@link liveAttestations}.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Every attestation is returned, stale ones flagged, so an owner surface can
+ * show what a previous registration left behind; anything that renders a
+ * verified badge takes {@link isHandleVerified} / {@link liveAttestations}.
  */
-export async function fetchAttestations(rpc, programId, handleAccount, registeredAt) {
+export async function fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -205,7 +217,7 @@ export async function fetchAttestations(rpc, programId, handleAccount, registere
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const decoded = decodeAttestation(raw, a.pubkey, registeredAt);
+        const decoded = decodeAttestation(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
         // attestation to this handle. A malformed account is skipped, not fatal.

package/dist/clearRecords.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `clear_records` (#8139): bulk-invalidate every record/text-record/
+ * attestation on a handle RIGHT NOW, without a transfer, by bumping
+ * `Handle.records_cleared_at` to the current time. The accounts
+ * (`accounts.ts` `ParsedHandle.recordsClearedAt`) and read-side staleness
+ * rule (every decoder in `records.ts` / `textRecords.ts` / `attestation.ts`:
+ * `updated_at < recordsClearedAt` is stale, alongside the `registeredAt`
+ * epoch rule) have existed since #8139 shipped; this module is the one
+ * missing piece — the instruction builder to actually trigger a clear
+ * (WP #8212).
+ *
+ * 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.
+ *
+ * # Authority: STRICT current-authority, no delegate
+ *
+ * `clear_records` is gated by `require_current_authority` in lib.rs — the
+ * SAME strict check `lock_handle`/`initiate_unlock`/`complete_unlock` use
+ * (see `lock.ts`'s module docs), not the record-editing delegate model
+ * (`require_record_edit_authority`, `recordWrite.ts`'s
+ * `RecordEditAuthorityParams`). A handle's active `RecordDelegate` can add,
+ * edit, and verify individual records, but CANNOT bulk-invalidate all of
+ * them — that stays an owner/NFT-holder-only action, on purpose: nuking
+ * every record is a much bigger blast radius than editing one. There is
+ * deliberately no `recordDelegate` param here.
+ *
+ * A TOKENIZED handle's current holder appends their ATA for the handle's
+ * NFT mint as the sole remaining account (`holderTokenAccount`), exactly
+ * like `lock.ts`'s `LockParams`/`UnlockParams`; omit it for an untokenized
+ * handle.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** Anchor instruction discriminator: `sha256("global:clear_records")[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 CLEAR_RECORDS_DISCRIMINATOR: Uint8Array;
+export interface ClearRecordsParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's CURRENT authority (untokenized owner, or NFT holder).
+     *  Signer, writable — also pays the one-time account grow through
+     *  `records_cleared_at`'s extension region on a handle that has never
+     *  been grown that far. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: 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 `clear_records` — bump `Handle.records_cleared_at` to now, so every
+ * record/text-record/attestation with an `updated_at` before this instant
+ * reads as stale everywhere in this SDK, without touching any of those
+ * accounts individually. Idempotent (re-clearing just re-stamps the clock).
+ */
+export declare function buildClearRecordsIx(p: ClearRecordsParams): BuiltInstruction;

package/dist/clearRecords.js

@@ -0,0 +1,69 @@
+/**
+ * `clear_records` (#8139): bulk-invalidate every record/text-record/
+ * attestation on a handle RIGHT NOW, without a transfer, by bumping
+ * `Handle.records_cleared_at` to the current time. The accounts
+ * (`accounts.ts` `ParsedHandle.recordsClearedAt`) and read-side staleness
+ * rule (every decoder in `records.ts` / `textRecords.ts` / `attestation.ts`:
+ * `updated_at < recordsClearedAt` is stale, alongside the `registeredAt`
+ * epoch rule) have existed since #8139 shipped; this module is the one
+ * missing piece — the instruction builder to actually trigger a clear
+ * (WP #8212).
+ *
+ * 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.
+ *
+ * # Authority: STRICT current-authority, no delegate
+ *
+ * `clear_records` is gated by `require_current_authority` in lib.rs — the
+ * SAME strict check `lock_handle`/`initiate_unlock`/`complete_unlock` use
+ * (see `lock.ts`'s module docs), not the record-editing delegate model
+ * (`require_record_edit_authority`, `recordWrite.ts`'s
+ * `RecordEditAuthorityParams`). A handle's active `RecordDelegate` can add,
+ * edit, and verify individual records, but CANNOT bulk-invalidate all of
+ * them — that stays an owner/NFT-holder-only action, on purpose: nuking
+ * every record is a much bigger blast radius than editing one. There is
+ * deliberately no `recordDelegate` param here.
+ *
+ * A TOKENIZED handle's current holder appends their ATA for the handle's
+ * NFT mint as the sole remaining account (`holderTokenAccount`), exactly
+ * like `lock.ts`'s `LockParams`/`UnlockParams`; omit it for an untokenized
+ * handle.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Anchor instruction discriminator: `sha256("global:clear_records")[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 CLEAR_RECORDS_DISCRIMINATOR = Uint8Array.from([
+    150, 232, 238, 45, 8, 105, 50, 153,
+]);
+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);
+}
+/**
+ * Build `clear_records` — bump `Handle.records_cleared_at` to now, so every
+ * record/text-record/attestation with an `updated_at` before this instant
+ * reads as stale everywhere in this SDK, without touching any of those
+ * accounts individually. Idempotent (re-clearing just re-stamps the clock).
+ */
+export function buildClearRecordsIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { 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: CLEAR_RECORDS_DISCRIMINATOR.slice() };
+}

package/dist/index.d.ts

@@ -38,6 +38,12 @@ export * from "./textRecords.js";
 export * from "./lock.js";
 export * from "./integrator.js";
 export * from "./voucher.js";
+export * from "./agent.js";
+export * from "./register.js";
+export * from "./accounts.js";
+export * from "./x402.js";
+export * from "./recordWrite.js";
+export * from "./clearRecords.js";
 import { type Chain, type Resolved } from "./types.js";
 import { WasmResolver } from "./wasm.js";
 import { type HandleRecord } from "./records.js";

package/dist/index.js

@@ -38,6 +38,19 @@ export * from "./textRecords.js";
 export * from "./lock.js";
 export * from "./integrator.js";
 export * from "./voucher.js";
+export * from "./agent.js";
+export * from "./register.js";
+// Was previously imported here for internal use only, never re-exported —
+// promoted to public API 2026-09-22 because a second real package (mcp/)
+// now needs `parseHandleAccount`/`RpcFn` directly rather than duplicating
+// this decoder (the Handle account's `Option<Pubkey>` fields are
+// variable-width Borsh — a hand-rolled offset guess here would be exactly
+// the kind of drift docs/record-trust.md's "one implementation" rule
+// exists to prevent).
+export * from "./accounts.js";
+export * from "./x402.js";
+export * from "./recordWrite.js";
+export * from "./clearRecords.js";
 import { ResolveError, CHAIN_COIN_TYPE } from "./types.js";
 import { parseName } from "./parse.js";
 import { encodeBase58, decodeBase58_32 } from "./base58.js";
@@ -136,7 +149,7 @@ export function createResolver(config) {
         // behind by a previous registration of the same name is never resolved,
         // and a stale `verified: true` is never surfaced.
         if (chain !== "X1" && chain !== "SOL") {
-            const live = liveRecords(await fetchRecords(rpc, programBase58, pda, handle.registeredAt));
+            const live = liveRecords(await fetchRecords(rpc, programBase58, pda, handle.registeredAt, handle.recordsClearedAt));
             const record = live.find((r) => r.coinType === CHAIN_COIN_TYPE[chain]);
             if (!record) {
                 throw new ResolveError("no-record-for-chain", `@${canonical} has no ${chain} record`, input);
@@ -166,7 +179,7 @@ export function createResolver(config) {
             throw new ResolveError("unrecognized", `per-chain records exist only for @handles, not .${parsed.namespace} domains`, input);
         }
         const { pda, handle } = await fetchHandle(parsed.canonical, input);
-        return fetchRecords(rpc, programBase58, pda, handle.registeredAt);
+        return fetchRecords(rpc, programBase58, pda, handle.registeredAt, handle.recordsClearedAt);
     }
     async function resolve(input, opts) {
         const chain = opts?.chain ?? "X1";

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 };
+}