@x1id/resolve 0.2.1 → 0.3.0

package/dist/control.js

@@ -0,0 +1,316 @@
+/**
+ * Control-verification primitive — prove to a third party that a wallet
+ * currently controls a `@handle`. Companion to docs/control-proof.md, which
+ * is normative; this file implements it.
+ *
+ * The flow has exactly two SDK entry points, one per side:
+ *
+ * - **Verifier** calls {@link createControlChallenge}: it generates a fresh
+ *   nonce, reads the handle's CURRENT ownership epoch
+ *   (`Handle.registered_at`) from chain, and returns the challenge the
+ *   prover must sign. The verifier stores the returned object (nonce is
+ *   single-use, proofs expire — see the spec).
+ * - The prover signs the raw UTF-8 bytes of `challenge` with the wallet key
+ *   that controls the handle (no wallet prefix — see the spec's envelope
+ *   section) and returns `(signer, signature)`.
+ * - **Verifier** calls {@link verifyControlProof} with the ISSUED challenge
+ *   object (never a challenge string received from the prover) and the
+ *   proof. It re-reads the handle, requires the epoch to still match,
+ *   resolves who currently holds authority (`require_current_authority`
+ *   semantics: untokenized → `Handle.owner`; tokenized → the NFT holder,
+ *   NFT in that holder's associated token account), and verifies the
+ *   signature RFC-8032-strictly.
+ *
+ * Challenge format (built by `handle_normalize::control_challenge` in Rust
+ * and {@link buildControlChallenge} here — byte-identical by test):
+ *
+ *     x1-handles:ctl:v1:<handle>:<registered_at>:<nonce>
+ *
+ * The `ctl` purpose tag makes this space disjoint from the record
+ * verification challenges (`x1-handles:v1:...`): a signature obtained for a
+ * record verification can never validate as a control proof, and vice versa.
+ */
+import { ResolveError } from "./types.js";
+import { normalizeHandle } from "./parse.js";
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { DEFAULT_HANDLE_PROGRAM, makeAccountReader, nftHolder, parseHandleAccount, } from "./accounts.js";
+/** `<protocol>:<purpose>:<version>:` — everything a control challenge starts
+ *  with, and nothing a record-verification challenge ever starts with (their
+ *  second segment is the literal `v1`, and neither a canonical handle nor a
+ *  nonce may contain `:`). */
+export const CONTROL_CHALLENGE_PREFIX = "x1-handles:ctl:v1:";
+/** Nonce charset shared with the Rust crate: ASCII alphanumeric, 1..=64
+ *  chars — anything else could smuggle a `:` separator (or be refused by
+ *  the Rust side, which must stay byte-identical). */
+const NONCE_RE = /^[0-9A-Za-z]{1,64}$/;
+function isCanonicalHandle(handle) {
+    try {
+        return normalizeHandle(handle) === handle;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the exact challenge string — byte-identical to the Rust
+ * `handle_normalize::control_challenge`. Throws {@link ResolveError}
+ * (`invalid-handle`) for a non-canonical handle and `RangeError` for a
+ * nonce outside the shared charset, rather than silently producing a string
+ * the Rust side would refuse.
+ *
+ * Verifiers normally never call this directly — {@link
+ * createControlChallenge} does, after reading `registeredAt` from chain, so
+ * a challenge cannot be built against a guessed or stale epoch.
+ */
+export function buildControlChallenge(handle, registeredAt, nonce) {
+    if (!isCanonicalHandle(handle)) {
+        throw new ResolveError("invalid-handle", `"${handle}" is not a canonical handle`, handle);
+    }
+    if (!NONCE_RE.test(nonce)) {
+        throw new RangeError("nonce must be 1-64 ASCII alphanumeric characters");
+    }
+    return `${CONTROL_CHALLENGE_PREFIX}${handle}:${registeredAt}:${nonce}`;
+}
+/**
+ * Parse a control challenge string, or null for anything that is not one —
+ * including every record-verification challenge (`x1-handles:v1:...`), whose
+ * signatures must never be accepted as control proofs.
+ */
+export function parseControlChallenge(challenge) {
+    const parts = challenge.split(":");
+    if (parts.length !== 6)
+        return null;
+    const [protocol, purpose, version, handle, epoch, nonce] = parts;
+    if (protocol !== "x1-handles" || purpose !== "ctl" || version !== "v1")
+        return null;
+    if (!isCanonicalHandle(handle))
+        return null;
+    if (!/^-?[0-9]+$/.test(epoch))
+        return null;
+    if (!NONCE_RE.test(nonce))
+        return null;
+    return { handle, registeredAt: BigInt(epoch), nonce };
+}
+/**
+ * Generate a verifier-issued nonce: `bytes` bytes (>= 16, the spec's entropy
+ * floor) from the platform CSPRNG, hex-encoded to stay inside the shared
+ * nonce charset. The nonce is SINGLE-USE — store it with the issued
+ * challenge and delete it the moment a proof against it is checked, pass or
+ * fail. A prover-chosen nonce is not a nonce; see docs/control-proof.md.
+ */
+export function generateControlNonce(bytes = 16) {
+    if (!Number.isInteger(bytes) || bytes < 16 || bytes > 32) {
+        throw new RangeError("nonce entropy must be 16-32 bytes");
+    }
+    const cryptoObj = globalThis.crypto;
+    if (!cryptoObj?.getRandomValues) {
+        throw new Error("No CSPRNG available (globalThis.crypto.getRandomValues)");
+    }
+    const raw = cryptoObj.getRandomValues(new Uint8Array(bytes));
+    return Array.from(raw, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Shared handle fetch: derive the PDA, require registry ownership, parse. */
+async function fetchHandle(cfg, reader, canonical) {
+    const decodedProgram = decodeBase58_32(cfg.handleProgramId ?? DEFAULT_HANDLE_PROGRAM);
+    if (!decodedProgram) {
+        throw new Error("handleProgramId is not a valid base58 address");
+    }
+    const account = cfg.wasm.deriveHandleAccount(canonical, decodedProgram);
+    if (!account) {
+        throw new ResolveError("invalid-handle", `"${canonical}" is not a valid handle`, canonical);
+    }
+    const h = await reader.accountInfo(encodeBase58(account));
+    // An account at the PDA that the registry does not own is not a handle.
+    if (!h || h.owner !== encodeBase58(decodedProgram))
+        return null;
+    const handle = parseHandleAccount(h.data);
+    if (!handle) {
+        throw new ResolveError("rpc-error", `@${canonical} returned a malformed account`, canonical);
+    }
+    return handle;
+}
+/**
+ * Verifier side, step 1: issue a challenge for a handle.
+ *
+ * Reads the handle's CURRENT `registered_at` from chain and binds the
+ * challenge to it — there is no way to obtain a challenge through this API
+ * without the live epoch in hand, which is what makes a past owner's proof
+ * worthless the moment the name changes hands.
+ *
+ * Store the returned object server-side (it is the only thing
+ * {@link verifyControlProof} accepts), enforce single use of `nonce`, and
+ * enforce a max proof age against `issuedAt` (the spec recommends 5 minutes).
+ *
+ * @throws {ResolveError} `invalid-handle` for bad input, `not-found` for an
+ * unregistered handle, `rpc-error` for transport problems.
+ */
+export async function createControlChallenge(cfg, handleInput) {
+    const canonical = normalizeHandle(handleInput); // throws invalid-handle
+    const reader = makeAccountReader(cfg.rpcUrl, cfg.fetchImpl);
+    const handle = await fetchHandle(cfg, reader, canonical);
+    if (!handle) {
+        throw new ResolveError("not-found", `@${canonical} is not registered`, handleInput);
+    }
+    const nonce = generateControlNonce();
+    return {
+        challenge: buildControlChallenge(canonical, handle.registeredAt, nonce),
+        handle: canonical,
+        registeredAt: handle.registeredAt,
+        nonce,
+        issuedAt: Date.now(),
+    };
+}
+/**
+ * Verifier side, step 2: check a proof against the challenge YOU issued.
+ *
+ * Takes the stored {@link ControlChallenge} — never a challenge string
+ * received from the prover — and re-derives the signed bytes from its
+ * fields, so neither side can substitute a different string. Then:
+ *
+ * 1. re-reads the handle and requires `registered_at` to still equal the
+ *    epoch the challenge was issued under (`epoch-changed` otherwise —
+ *    the name changed hands after issuance);
+ * 2. resolves the CURRENT authority with `require_current_authority`
+ *    semantics — untokenized → `Handle.owner`; tokenized → the NFT holder,
+ *    and only with the NFT in that holder's associated token account
+ *    (`Handle.owner` is stale once tokenized and is never consulted);
+ * 3. requires `proof.signer` to be that authority;
+ * 4. verifies the 64-byte ed25519 signature over the raw UTF-8 challenge
+ *    bytes, RFC-8032-strictly.
+ *
+ * Verification outcomes come back as `{ valid: false, reason }` — only
+ * transport failures throw (`ResolveError` `rpc-error`). Nonce single-use
+ * and max proof age are the CALLER's responsibility: delete the stored
+ * challenge the moment this returns, whatever the outcome, and refuse
+ * challenges older than your proof-age limit before calling.
+ */
+export async function verifyControlProof(cfg, issued, proof) {
+    // Re-derive the signed bytes from the issued fields; also revalidates them.
+    const challenge = buildControlChallenge(issued.handle, issued.registeredAt, issued.nonce);
+    const reader = makeAccountReader(cfg.rpcUrl, cfg.fetchImpl);
+    const handle = await fetchHandle(cfg, reader, issued.handle);
+    if (!handle) {
+        return {
+            valid: false,
+            reason: "handle-not-registered",
+            message: `@${issued.handle} is not registered`,
+        };
+    }
+    if (handle.registeredAt !== issued.registeredAt) {
+        return {
+            valid: false,
+            reason: "epoch-changed",
+            message: `@${issued.handle} changed ownership epoch after the challenge was issued (${issued.registeredAt} -> ${handle.registeredAt}); issue a fresh challenge`,
+        };
+    }
+    // Current authority, require_current_authority semantics.
+    let authority;
+    const tokenized = handle.nftMint !== null;
+    if (handle.nftMint === null) {
+        authority = encodeBase58(handle.owner);
+    }
+    else {
+        let holder;
+        try {
+            holder = await nftHolder(reader, cfg.wasm, issued.handle, handle.nftMint, issued.handle);
+        }
+        catch (e) {
+            if (e instanceof ResolveError && e.reason === "nft-burned") {
+                return {
+                    valid: false,
+                    reason: "nft-burned",
+                    message: `@${issued.handle}'s NFT has been burned — nobody controls the name`,
+                };
+            }
+            throw e; // rpc-error: infrastructure, not a verdict on the proof
+        }
+        if (holder.verification !== "verified") {
+            return {
+                valid: false,
+                reason: "nft-not-in-authority-ata",
+                message: `@${issued.handle}'s NFT is not in its holder's associated token account; the registry does not recognise that wallet as the name's authority`,
+            };
+        }
+        authority = holder.address;
+    }
+    if (proof.signer !== authority) {
+        return {
+            valid: false,
+            reason: "signer-not-authority",
+            message: `${proof.signer} does not currently control @${issued.handle}`,
+        };
+    }
+    const publicKey = decodeBase58_32(proof.signer);
+    if (!publicKey) {
+        return {
+            valid: false,
+            reason: "signer-not-authority",
+            message: `"${proof.signer}" is not a valid base58 address`,
+        };
+    }
+    const verify = cfg.verifyEd25519 ?? verifyEd25519Strict;
+    const ok = await verify(publicKey, new TextEncoder().encode(challenge), proof.signature);
+    if (!ok) {
+        return {
+            valid: false,
+            reason: "bad-signature",
+            message: "signature does not verify over the challenge bytes",
+        };
+    }
+    return {
+        valid: true,
+        handle: issued.handle,
+        signer: proof.signer,
+        registeredAt: issued.registeredAt,
+        tokenized,
+    };
+}
+/**
+ * RFC-8032-strict ed25519 verification via WebCrypto (`Ed25519`), available
+ * in Node 20+ and current browsers. Both are backed by implementations that
+ * reject a non-canonical `s >= L` (the malleability the spec's strictness
+ * requirement exists for) — the test suite pins this with known-answer
+ * vectors, including a rejected `s + L` forgery of a valid signature.
+ *
+ * Returns false for anything malformed (wrong lengths, off-curve key,
+ * invalid signature); throws only when the runtime has no Ed25519 WebCrypto
+ * at all — pass `verifyEd25519` in {@link ControlConfig} there, using a
+ * strict library named in docs/control-proof.md.
+ */
+export async function verifyEd25519Strict(publicKey, message, signature) {
+    if (publicKey.length !== 32 || signature.length !== 64)
+        return false;
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("WebCrypto is unavailable in this runtime; pass an RFC-8032-strict verifyEd25519 in ControlConfig");
+    }
+    let key;
+    try {
+        key = await subtle.importKey("raw", publicKey, { name: "Ed25519" }, false, [
+            "verify",
+        ]);
+    }
+    catch {
+        // Either the runtime has no Ed25519, or it refused THESE key bytes. Probe
+        // with a known-good key (RFC 8032 TEST 1) to tell the two apart: a
+        // missing algorithm must be loud, a bad key is just an invalid proof.
+        const probe = new Uint8Array([
+            0xd7, 0x5a, 0x98, 0x01, 0x82, 0xb1, 0x0a, 0xb7, 0xd5, 0x4b, 0xfe, 0xd3, 0xc9, 0x64, 0x07,
+            0x3a, 0x0e, 0xe1, 0x72, 0xf3, 0xda, 0xa6, 0x23, 0x25, 0xaf, 0x02, 0x1a, 0x68, 0xf7, 0x07,
+            0x51, 0x1a,
+        ]);
+        try {
+            await subtle.importKey("raw", probe, { name: "Ed25519" }, false, ["verify"]);
+        }
+        catch {
+            throw new Error("This runtime's WebCrypto lacks Ed25519; pass an RFC-8032-strict verifyEd25519 in ControlConfig");
+        }
+        return false;
+    }
+    try {
+        return await subtle.verify("Ed25519", key, signature, message);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/delegate.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Delegated record-editing authority (`RecordDelegate`, #7374): instruction
+ * builders and account decoding for `set_record_delegate` /
+ * `revoke_record_delegate`, plus the optional-delegation account slot the
+ * record-editing instructions grew.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return a
+ * transport-neutral {@link BuiltInstruction}; adapt to web3.js with:
+ *
+ * ```ts
+ * new TransactionInstruction({
+ *   programId: new PublicKey(ix.programId),
+ *   keys: ix.keys.map((k) => ({ pubkey: new PublicKey(k.pubkey), isSigner: k.isSigner, isWritable: k.isWritable })),
+ *   data: Buffer.from(ix.data),
+ * });
+ * ```
+ *
+ * # Deriving the PDA
+ *
+ * The delegation account lives at `["delegate", handlePda]` under the
+ * registry program (seed constant: {@link RECORD_DELEGATE_SEED}). This module
+ * deliberately does NOT derive PDAs — `find_program_address` needs an
+ * ed25519 on-curve check, and this package's one rule about that is to never
+ * hand-roll it in TypeScript (see `wasm.ts`). Derive it with your runtime's
+ * canonical implementation, e.g. web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(RECORD_DELEGATE_SEED), handlePda.toBytes()],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The wire rules the on-chain program enforces (mirror of lib.rs)
+ *
+ * - `set_record_delegate` / `revoke_record_delegate` are gated by the STRICT
+ *   authority check: for a TOKENIZED handle append the holder's ATA for the
+ *   handle's NFT mint as the first extra (remaining) account.
+ * - The record-editing instructions (`create_record`, `update_record`,
+ *   `verify_record_*`, `close_record`) end in a named OPTIONAL
+ *   `record_delegate` account:
+ *   - a DELEGATE caller passes the delegation PDA there (and never any ATA);
+ *   - an untokenized OWNER simply omits the slot (pre-#7374 account list);
+ *   - a tokenized OWNER must pass the "explicitly None" placeholder — the
+ *     program id itself — in that slot, ahead of the ATA remaining account.
+ *     {@link recordDelegateNonePlaceholder} names that convention.
+ * - A delegation only authorizes while `delegatedAt >=
+ *   handle.registered_at`; any transfer/sale/recovery/re-registration bumps
+ *   the epoch and strands it (`StaleRecordDelegate`, code 6043). A bearer-NFT
+ *   marketplace trade does NOT bump the epoch — an NFT buyer should check
+ *   for, and revoke, an existing delegation.
+ */
+/** Seed prefix of the delegation PDA: `["delegate", handlePda]`. */
+export declare const RECORD_DELEGATE_SEED = "delegate";
+/** Anchor account discriminator: `sha256("account:RecordDelegate")[0..8]`. */
+export declare const RECORD_DELEGATE_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:set_record_delegate")[0..8]`. */
+export declare const SET_RECORD_DELEGATE_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:revoke_record_delegate")[0..8]`. */
+export declare const REVOKE_RECORD_DELEGATE_DISCRIMINATOR: Uint8Array;
+/** `RecordDelegate` account size: disc(8) handle(32) delegate(32) i64(8) bump(1). */
+export declare const RECORD_DELEGATE_LEN = 81;
+/** A 32-byte address, or its base58 spelling. */
+export type AddressLike = Uint8Array | string;
+/** One account in a {@link BuiltInstruction}, base58 like the rest of this
+ *  package's public API. */
+export interface InstructionKey {
+    readonly pubkey: string;
+    readonly isSigner: boolean;
+    readonly isWritable: boolean;
+}
+/** A transport-neutral instruction — see the module docs for the two-line
+ *  web3.js adapter. */
+export interface BuiltInstruction {
+    readonly programId: string;
+    readonly keys: readonly InstructionKey[];
+    readonly data: Uint8Array;
+}
+/** Decoded `RecordDelegate` account. */
+export interface RecordDelegate {
+    /** The `Handle` PDA this delegation is for (base58). */
+    readonly handle: string;
+    /** The wallet allowed to edit the handle's records (base58). */
+    readonly delegate: string;
+    /** Unix seconds the delegation was (last) granted. Trust it only while
+     *  `delegatedAt >= handle.registered_at` — see the module docs. */
+    readonly delegatedAt: bigint;
+    readonly bump: number;
+}
+/**
+ * Decode a `RecordDelegate` account's raw data (exactly what an RPC
+ * `getAccountInfo` returns for the `["delegate", handlePda]` PDA), or null if
+ * the bytes are not a `RecordDelegate`.
+ */
+export declare function decodeRecordDelegate(data: Uint8Array): RecordDelegate | null;
+export interface SetRecordDelegateParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the delegation account's rent on first grant. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's CURRENT authority (owner, or NFT holder). Signer. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** The `["delegate", handle]` PDA — derive per the module docs. */
+    readonly recordDelegate: AddressLike;
+    /** The wallet being granted record-editing rights. */
+    readonly delegate: AddressLike;
+    /** TOKENIZED handles only: the owner'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 `set_record_delegate` — grant (or overwrite, re-stamping
+ * `delegatedAt`) the handle's single record-editing delegation.
+ */
+export declare function buildSetRecordDelegateIx(p: SetRecordDelegateParams): BuiltInstruction;
+export interface RevokeRecordDelegateParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's CURRENT authority. Signer. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** The `["delegate", handle]` PDA being closed. */
+    readonly recordDelegate: AddressLike;
+    /** Receives the closed account's rent — any account the caller chooses. */
+    readonly recipient: AddressLike;
+    /** TOKENIZED handles only — same rule as {@link SetRecordDelegateParams}. */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `revoke_record_delegate` — close the delegation, rent to
+ * `recipient`. Also how a NEW owner/NFT-holder sweeps a previous owner's
+ * stale delegation.
+ */
+export declare function buildRevokeRecordDelegateIx(p: RevokeRecordDelegateParams): BuiltInstruction;
+/**
+ * The named-optional-account "explicitly None" entry for a record-editing
+ * instruction's trailing `record_delegate` slot: Anchor's convention is the
+ * program's own id, read-only, non-signer. A TOKENIZED owner must place this
+ * ahead of their ATA remaining-account; an untokenized owner simply omits
+ * the slot instead.
+ */
+export declare function recordDelegateNonePlaceholder(programId: AddressLike): InstructionKey;
+/**
+ * The populated `record_delegate` slot a DELEGATE appends to a
+ * record-editing instruction's account list (read-only — the record
+ * instructions never mutate the delegation).
+ */
+export declare function recordDelegateSomeSlot(recordDelegate: AddressLike): InstructionKey;

package/dist/delegate.js

@@ -0,0 +1,166 @@
+/**
+ * Delegated record-editing authority (`RecordDelegate`, #7374): instruction
+ * builders and account decoding for `set_record_delegate` /
+ * `revoke_record_delegate`, plus the optional-delegation account slot the
+ * record-editing instructions grew.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return a
+ * transport-neutral {@link BuiltInstruction}; adapt to web3.js with:
+ *
+ * ```ts
+ * new TransactionInstruction({
+ *   programId: new PublicKey(ix.programId),
+ *   keys: ix.keys.map((k) => ({ pubkey: new PublicKey(k.pubkey), isSigner: k.isSigner, isWritable: k.isWritable })),
+ *   data: Buffer.from(ix.data),
+ * });
+ * ```
+ *
+ * # Deriving the PDA
+ *
+ * The delegation account lives at `["delegate", handlePda]` under the
+ * registry program (seed constant: {@link RECORD_DELEGATE_SEED}). This module
+ * deliberately does NOT derive PDAs — `find_program_address` needs an
+ * ed25519 on-curve check, and this package's one rule about that is to never
+ * hand-roll it in TypeScript (see `wasm.ts`). Derive it with your runtime's
+ * canonical implementation, e.g. web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(RECORD_DELEGATE_SEED), handlePda.toBytes()],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The wire rules the on-chain program enforces (mirror of lib.rs)
+ *
+ * - `set_record_delegate` / `revoke_record_delegate` are gated by the STRICT
+ *   authority check: for a TOKENIZED handle append the holder's ATA for the
+ *   handle's NFT mint as the first extra (remaining) account.
+ * - The record-editing instructions (`create_record`, `update_record`,
+ *   `verify_record_*`, `close_record`) end in a named OPTIONAL
+ *   `record_delegate` account:
+ *   - a DELEGATE caller passes the delegation PDA there (and never any ATA);
+ *   - an untokenized OWNER simply omits the slot (pre-#7374 account list);
+ *   - a tokenized OWNER must pass the "explicitly None" placeholder — the
+ *     program id itself — in that slot, ahead of the ATA remaining account.
+ *     {@link recordDelegateNonePlaceholder} names that convention.
+ * - A delegation only authorizes while `delegatedAt >=
+ *   handle.registered_at`; any transfer/sale/recovery/re-registration bumps
+ *   the epoch and strands it (`StaleRecordDelegate`, code 6043). A bearer-NFT
+ *   marketplace trade does NOT bump the epoch — an NFT buyer should check
+ *   for, and revoke, an existing delegation.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Seed prefix of the delegation PDA: `["delegate", handlePda]`. */
+export const RECORD_DELEGATE_SEED = "delegate";
+/** Anchor account discriminator: `sha256("account:RecordDelegate")[0..8]`. */
+export const RECORD_DELEGATE_DISCRIMINATOR = Uint8Array.from([
+    194, 175, 15, 64, 162, 184, 224, 111,
+]);
+/** Anchor instruction discriminator: `sha256("global:set_record_delegate")[0..8]`. */
+export const SET_RECORD_DELEGATE_DISCRIMINATOR = Uint8Array.from([
+    95, 62, 249, 218, 113, 197, 119, 51,
+]);
+/** Anchor instruction discriminator: `sha256("global:revoke_record_delegate")[0..8]`. */
+export const REVOKE_RECORD_DELEGATE_DISCRIMINATOR = Uint8Array.from([
+    53, 157, 215, 100, 80, 63, 168, 217,
+]);
+/** `RecordDelegate` account size: disc(8) handle(32) delegate(32) i64(8) bump(1). */
+export const RECORD_DELEGATE_LEN = 81;
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+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) {
+    // Round-trip through bytes so a non-canonical base58 spelling and a byte
+    // input both come out identically.
+    return encodeBase58(toBytes32(v, what));
+}
+/**
+ * Decode a `RecordDelegate` account's raw data (exactly what an RPC
+ * `getAccountInfo` returns for the `["delegate", handlePda]` PDA), or null if
+ * the bytes are not a `RecordDelegate`.
+ */
+export function decodeRecordDelegate(data) {
+    if (data.length !== RECORD_DELEGATE_LEN)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (data[i] !== RECORD_DELEGATE_DISCRIMINATOR[i])
+            return null;
+    }
+    const delegatedAt = new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(72, true);
+    return {
+        handle: encodeBase58(data.slice(8, 40)),
+        delegate: encodeBase58(data.slice(40, 72)),
+        delegatedAt,
+        bump: data[80],
+    };
+}
+/**
+ * Build `set_record_delegate` — grant (or overwrite, re-stamping
+ * `delegatedAt`) the handle's single record-editing delegation.
+ */
+export function buildSetRecordDelegateIx(p) {
+    const data = new Uint8Array(8 + 32);
+    data.set(SET_RECORD_DELEGATE_DISCRIMINATOR, 0);
+    data.set(toBytes32(p.delegate, "delegate"), 8);
+    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: false },
+        { pubkey: toBase58(p.recordDelegate, "recordDelegate"), 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 };
+}
+/**
+ * Build `revoke_record_delegate` — close the delegation, rent to
+ * `recipient`. Also how a NEW owner/NFT-holder sweeps a previous owner's
+ * stale delegation.
+ */
+export function buildRevokeRecordDelegateIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.recordDelegate, "recordDelegate"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), 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: REVOKE_RECORD_DELEGATE_DISCRIMINATOR.slice(),
+    };
+}
+/**
+ * The named-optional-account "explicitly None" entry for a record-editing
+ * instruction's trailing `record_delegate` slot: Anchor's convention is the
+ * program's own id, read-only, non-signer. A TOKENIZED owner must place this
+ * ahead of their ATA remaining-account; an untokenized owner simply omits
+ * the slot instead.
+ */
+export function recordDelegateNonePlaceholder(programId) {
+    return { pubkey: toBase58(programId, "programId"), isSigner: false, isWritable: false };
+}
+/**
+ * The populated `record_delegate` slot a DELEGATE appends to a
+ * record-editing instruction's account list (read-only — the record
+ * instructions never mutate the delegation).
+ */
+export function recordDelegateSomeSlot(recordDelegate) {
+    return { pubkey: toBase58(recordDelegate, "recordDelegate"), isSigner: false, isWritable: false };
+}

package/dist/index.d.ts

@@ -28,8 +28,19 @@ export * from "./types.js";
 export { normalizeHandle, parseName, looksLikeName, type ParsedName } from "./parse.js";
 export { WasmResolver, type WasmTld } from "./wasm.js";
 export { encodeBase58, decodeBase58_32 } from "./base58.js";
+export { decodeRecord, liveRecords, chainForCoinType, valueToAddress, fetchRecords, RECORD_LEN, RECORD_DISC, type HandleRecord, } from "./records.js";
+export { buildControlChallenge, parseControlChallenge, generateControlNonce, createControlChallenge, verifyControlProof, verifyEd25519Strict, CONTROL_CHALLENGE_PREFIX, type ControlChallenge, type ControlConfig, type ControlProof, type ControlVerification, type ControlFailureReason, } from "./control.js";
+export * from "./delegate.js";
+export * from "./subname.js";
+export * from "./recordCount.js";
+export * from "./attestation.js";
+export * from "./textRecords.js";
+export * from "./lock.js";
+export * from "./integrator.js";
+export * from "./voucher.js";
 import { type Chain, type Resolved } from "./types.js";
 import { WasmResolver } from "./wasm.js";
+import { type HandleRecord } from "./records.js";
 export interface ResolverConfig {
     /** X1 RPC endpoint. */
     readonly rpcUrl: string;
@@ -62,6 +73,20 @@ export interface Resolver {
     resolve(input: string, opts?: ResolveOptions): Promise<Resolved>;
     /** Reverse: address to its primary name, or null if none is set. */
     reverse(address: string): Promise<string | null>;
+    /**
+     * Every per-chain payment record of a `@handle`, with the staleness rule
+     * of docs/record-trust.md already applied: records left behind by a
+     * previous registration of the same name (`updated_at <
+     * handle.registered_at`) come back flagged `stale` with `verified` forced
+     * false. Anything that resolves, displays, or counts must take
+     * `liveRecords(...)` of this; the full list exists so an owner surface
+     * can show what a previous owner left behind. `@handle` inputs only —
+     * X1NS domains keep their addresses elsewhere.
+     *
+     * @throws {ResolveError} `not-found` for an unregistered handle,
+     * `unrecognized` for a non-handle input.
+     */
+    records(input: string): Promise<readonly HandleRecord[]>;
     /** Clear the resolution cache. */
     clearCache(): void;
 }