@x1id/resolve 0.2.1 → 0.3.0

package/README.md

@@ -163,15 +163,34 @@ A pointer that fails any rule is treated as absent (falls through to X1NS, then
 A handle can carry addresses for several chains. Pass the one you want:
 
 ```ts
-await x1id.resolve("@jack", { chain: "X1" });   // default
+await x1id.resolve("@jack", { chain: "X1" });   // default — the handle's authority
 await x1id.resolve("@jack", { chain: "SOL" });  // X1 shares Solana's key format
-await x1id.resolve("@jack", { chain: "ETH" });  // → no-record-for-chain (see below)
+await x1id.resolve("@jack", { chain: "ETH" });  // the handle's ETH record, if one is set
+await x1id.resolve("@jack", { chain: "BTC" });  // the handle's BTC record, if one is set
 ```
 
-Today the SDK reads the owner's **X1/SVM** address. Per-chain records for ETH and
-BTC live in separate on-chain accounts the resolver does not read yet, so a
-request for those returns `no-record-for-chain` — an explicit "no record", never
-a wrong address on the wrong chain.
+For **X1/SOL** the SDK returns the handle's current authority. For **ETH/BTC**
+it reads the handle's per-chain `Record` accounts; a handle without a live
+record for the requested chain is `no-record-for-chain` — an explicit "no
+record", never a wrong address on the wrong chain.
+
+Every record is judged against the **universal staleness rule**
+(`docs/record-trust.md` in the x1-handles repo): a `Record` whose
+`updated_at` predates the handle's current `registered_at` was left behind by
+a **previous owner of the same name** (the Handle PDA survives a release +
+re-register, and records hang off it) and is treated as unset — its address
+is never resolved, and its stored `verified: true` is never surfaced. The
+rule is structural in this SDK: `decodeRecord`/`fetchRecords` require the
+handle's `registeredAt`, so there is no code path that returns an unjudged
+record.
+
+```ts
+// All records of a handle, stale ones flagged (verified forced false):
+const all = await x1id.records("@jack");
+// The ones that actually belong to the current owner:
+import { liveRecords } from "@x1id/resolve";
+const live = liveRecords(all);
+```
 
 ## Verification
 
@@ -192,13 +211,83 @@ path.
 | X1NS resolution (`.x1/.xnt/.xen`) | ✅ mainnet |
 | `@handle` resolution | ✅ on any RPC where the registry is deployed — **X1 testnet today**; mainnet on deploy |
 | Reverse lookup | ✅ on-chain `@handle` primary (testnet today) with X1NS primary-domain fallback (mainnet); X1NS results are `<domainAccount>.<tld>`, not a label |
-| Per-chain ETH/BTC records | 🔜 roadmap |
+| Per-chain ETH/BTC records | ✅ read with the staleness rule enforced structurally |
+| Control proofs (prove you control a `@handle`) | ✅ `createControlChallenge` / `verifyControlProof` — spec: `docs/control-proof.md` |
+| Records read (per-chain, staleness-enforced) | ✅ `fetchRecords` |
+| Subnames · gifts · integrator rev-share · name-lock · record-delegate · text records · attestations (write) | ✅ 0.3.0 — instruction builders; you sign & relay |
 | Registration / transfer / `set_primary` (write) | 🔜 roadmap — use [x1id.io](https://x1id.io) |
 
 The `@handle` registry program id is configurable (`handleProgramId`) and
 defaults to the canonical X1 deployment
 (`8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P`).
 
+## Beyond resolve: the registry write surface (0.3.0)
+
+`resolve()` / `reverse()` / `fetchRecords()` are read-only and need only an RPC.
+0.3.0 also ships **instruction builders** for the on-chain registry. Each
+returns an unsigned `BuiltInstruction` (`{ programId, keys, data }`) — you
+assemble it into a transaction, **sign, and relay** yourself; the SDK never
+holds keys. Every discriminator and account order matches the deployed program.
+
+**Read a handle's cross-chain records** (no wallet):
+
+```ts
+import { fetchRecords, liveRecords, valueToAddress } from "@x1id/resolve";
+
+// handleAccount = the ["handle", name] PDA; registeredAt from the handle account
+const records = await fetchRecords(rpc, programId, handleAccount, registeredAt);
+for (const r of liveRecords(records)) {
+  console.log(r.chain, valueToAddress(r.chain, r.value));
+}
+```
+
+**Issue a subname** (`team.you`), signed by the parent's current authority:
+
+```ts
+import { buildCreateSubnameIx } from "@x1id/resolve";
+
+const ix = buildCreateSubnameIx({
+  programId,
+  payer,      // signer — funds the subname account's rent
+  owner,      // signer — the parent handle's current authority (owner or NFT holder)
+  parent,     // the parent ["handle", name] PDA
+  subname,    // the ["subname", parent, label] PDA
+  label: "team",
+});
+// add `ix` to a transaction, sign with payer + owner, send.
+```
+
+**Gift a handle** (prepaid voucher; the recipient claims it later):
+
+```ts
+import { buildCreateVoucherIx, HandleType } from "@x1id/resolve";
+
+const ix = buildCreateVoucherIx({
+  programId, payer, config,   // config = the ["config"] PDA
+  voucher,                    // the ["voucher", name] PDA
+  handle,                     // the ["handle", name] PDA — must be unregistered
+  name: "gift1",
+  handleType: HandleType.Human,
+  recipient,                  // bind to a wallet, or null for an open claim code
+  expiresAt: Math.floor(Date.now() / 1000) + 30 * 86400,
+});
+```
+
+Also shipped, same build → sign → relay shape:
+
+| Capability | Builders |
+|---|---|
+| Integrator rev-share | `buildAddIntegratorIx`, `buildSetIntegratorRateIx`, `buildRemoveIntegratorIx` |
+| Name lock / timelocked unlock | `buildLockHandleIx`, `buildInitiateUnlockIx`, `buildCompleteUnlockIx`, `buildCancelUnlockIx` |
+| Record-write delegation | `buildSetRecordDelegateIx`, `buildRevokeRecordDelegateIx` |
+| Typed text records (website / avatar / socials) | `buildCreateTextRecordIx`, `buildUpdateTextRecordIx`, `buildCloseTextRecordIx` |
+| Domain / social attestations | `buildCreateAttestationIx`, `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`) |
+| Subname records / revoke | `buildRevokeSubnameIx`, `buildCreateSubnameRecordIx`, `buildUpdateSubnameRecordIx`, `buildCloseSubnameRecordIx` |
+| Voucher claim / refund | `buildClaimVoucherIx`, `buildRefundVoucherIx` |
+
+PDA seeds and account layouts are documented per module in the source and typed
+end to end. Reads need only an RPC; writes need a signer.
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:
@@ -240,6 +329,7 @@ interface ResolverConfig {
 interface Resolver {
   resolve(input: string, opts?: { chain?: "X1" | "SOL" | "ETH" | "BTC" }): Promise<Resolved>;
   reverse(address: string): Promise<string | null>;
+  records(input: string): Promise<readonly HandleRecord[]>; // stale ones flagged — see docs/record-trust.md
   clearCache(): void;
 }
 
@@ -258,6 +348,39 @@ Also exported: `parseName`, `looksLikeName`, `normalizeHandle`, `namespaceLabel`
 `encodeBase58`, `decodeBase58_32`, `ResolveError`, `CHAIN_COIN_TYPE` and the
 types `Resolved`, `Namespace`, `Chain`, `Verification`, `ResolveErrorCode`.
 
+Records: `decodeRecord(raw, account, registeredAt)`, `liveRecords`,
+`chainForCoinType`, `valueToAddress`, `fetchRecords`, `RECORD_LEN`,
+`RECORD_DISC`, type `HandleRecord`. The handle epoch (`registeredAt`) is a
+required parameter everywhere by design.
+
+Control proofs (spec: `docs/control-proof.md` in the x1-handles repo):
+
+```ts
+// Verifier side — reads the handle's current ownership epoch from chain,
+// generates a single-use nonce, returns the challenge to store and send:
+const issued = await createControlChallenge({ rpcUrl, wasm }, "@jack");
+// Prover signs the raw UTF-8 bytes of issued.challenge with the wallet key
+// that controls the handle (64-byte ed25519, no wallet envelope), then:
+const result = await verifyControlProof({ rpcUrl, wasm }, issued, { signer, signature });
+// result.valid === true ⇔ signer controls @jack right now, in this epoch.
+```
+
+Also exported for that flow: `buildControlChallenge`, `parseControlChallenge`,
+`generateControlNonce`, `verifyEd25519Strict` (RFC-8032-strict WebCrypto
+verifier; override via `ControlConfig.verifyEd25519` on runtimes without
+Ed25519 WebCrypto), `CONTROL_CHALLENGE_PREFIX` and the types
+`ControlChallenge`, `ControlConfig`, `ControlProof`, `ControlVerification`,
+`ControlFailureReason`.
+
+## Integrating into a wallet or explorer
+
+Dropping resolution into someone else's product — an explorer that shows
+`@handle` instead of an address, a wallet that resolves a recipient before it
+signs, an in-wallet (Snap-style) resolver — is a copy-paste job. See
+**[`docs/resolution-integration.md`](../docs/resolution-integration.md)**: a
+resolver singleton, a typed-error recipient flow, reverse lookup with the
+staleness rule, and a ~30-line React `<AddressName>`, all against this package.
+
 ## Developing
 
 ```bash

package/dist/accounts.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `@handle` registry account access shared by the resolver (`index.ts`), the
+ * per-chain record reader (`records.ts`) and the control-proof helpers
+ * (`control.ts`). One implementation of the byte layouts and of the
+ * "who currently holds authority" rule, so the three surfaces cannot drift.
+ *
+ * Everything here was extracted verbatim from `index.ts` (where the resolver
+ * tests exercise it); nothing in this module is public API on its own.
+ */
+import { type Verification } from "./types.js";
+import type { WasmResolver } from "./wasm.js";
+/** The @handle registry program on X1. Deployed on testnet today; the same id
+ *  is used on mainnet once deployed. Override via `handleProgramId` to point at
+ *  a different deployment. */
+export declare const DEFAULT_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
+export declare const TOKEN_ACCOUNT_MIN_LEN = 72;
+export declare const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+/** The fields of a `Handle` account readers need. */
+export interface ParsedHandle {
+    readonly name: string;
+    readonly owner: Uint8Array;
+    /**
+     * `Handle.registered_at` — the handle's CURRENT ownership epoch. Stamped
+     * fresh on every `register`/`register_reserved`, including a re-registration
+     * of a previously released name, and bumped by every native-market sale.
+     * Every per-handle record and proof must be judged against it — see
+     * docs/record-trust.md.
+     */
+    readonly registeredAt: bigint;
+    /** Set when the handle is tokenized (NFT extension present). */
+    readonly nftMint: Uint8Array | null;
+}
+export declare function readI64(data: Uint8Array, offset: number): bigint;
+export declare function readU64(data: Uint8Array, offset: number): bigint;
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Parse the `Handle` fields readers need. Port of `parse_handle` in
+ * tools/api — sequential, because `recovery` / `recovery_target` are
+ * `Option<Pubkey>` (Borsh: tag byte, then 32 bytes when `Some`) and shift
+ * `registered_at`. The NFT mint is read at the fixed base boundary, not the
+ * sequential position.
+ *
+ *   disc(8) name(32) name_len(1) owner(32) handle_type(1)
+ *   recovery: Option<Pubkey>  recovery_initiated_at: i64
+ *   recovery_target: Option<Pubkey>  registered_at: i64  bump(1)
+ *   [at 8+149: nft tag(1) mint(32)]
+ */
+export declare function parseHandleAccount(data: Uint8Array): ParsedHandle | null;
+/** A JSON-RPC call against the configured endpoint. */
+export type RpcFn = (method: string, params: unknown[]) => Promise<unknown>;
+export interface AccountReader {
+    readonly rpc: RpcFn;
+    /** Fetch raw account data plus the owning program, or null when the account
+     *  does not exist. */
+    accountInfo(address: string): Promise<{
+        readonly data: Uint8Array;
+        readonly owner: string;
+    } | null>;
+    /** Fetch raw account data, or null when the account does not exist. */
+    accountData(address: string): Promise<Uint8Array | null>;
+}
+/** Build the RPC plumbing every reader in this package shares. */
+export declare function makeAccountReader(rpcUrl: string, fetchImpl?: typeof fetch): AccountReader;
+/**
+ * Current holder of a tokenized handle: the owner of the single token
+ * account holding the handle's NFT (supply 1, decimals 0). Never falls back
+ * to `Handle.owner` — after the NFT changes hands that field names the
+ * previous owner, and paying it is the exact failure this SDK exists to
+ * prevent.
+ *
+ * Parity with the program's `require_current_authority` (and the
+ * resolver's `reverse()`): the program recognises the holder as the name's
+ * authority only when the NFT sits in the holder's **associated token
+ * account** for the mint. A holder whose NFT is parked elsewhere (an
+ * auxiliary account, a program escrow) still controls the token, so the
+ * address is returned — but as `unverified`, because the registry will not
+ * let that address act for the name until the NFT is back in its ATA.
+ *
+ * A burned NFT (mint supply 0) is `not-found` with reason `nft-burned`: the
+ * name has no holder, and no one — least of all the stale `owner` — may be
+ * paid for it. Any other failure to find the holder is an `rpc-error`.
+ */
+export declare function nftHolder(reader: AccountReader, wasm: WasmResolver, canonical: string, mint: Uint8Array, input: string): Promise<{
+    readonly address: string;
+    readonly verification: Verification;
+}>;

package/dist/accounts.js

@@ -0,0 +1,183 @@
+/**
+ * `@handle` registry account access shared by the resolver (`index.ts`), the
+ * per-chain record reader (`records.ts`) and the control-proof helpers
+ * (`control.ts`). One implementation of the byte layouts and of the
+ * "who currently holds authority" rule, so the three surfaces cannot drift.
+ *
+ * Everything here was extracted verbatim from `index.ts` (where the resolver
+ * tests exercise it); nothing in this module is public API on its own.
+ */
+import { ResolveError } from "./types.js";
+import { encodeBase58 } from "./base58.js";
+/** The @handle registry program on X1. Deployed on testnet today; the same id
+ *  is used on mainnet once deployed. Override via `handleProgramId` to point at
+ *  a different deployment. */
+export const DEFAULT_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
+// Handle account layout, mirrored from the on-chain program:
+//   discriminator(8) name(32) name_len(1) owner(32) ...
+// `owner` is the address an UNTOKENIZED handle resolves to. Once the handle
+// is tokenized (NFT extension present, see `parseHandleAccount`) the program
+// treats `owner` as informational only — authority is whoever holds the NFT —
+// and so must every reader.
+const HANDLE_OWNER_OFFSET = 41;
+// `Handle`'s fixed base allocation (`space = 8 + INIT_SPACE`). The NFT
+// extension, when present, is appended at this boundary regardless of the
+// compact Borsh length of the (variable, `Option`-bearing) struct content —
+// mirrors `Handle::NFT_EXT_OFFSET` in the program and `HANDLE_BASE_LEN` in
+// tools/api.
+const HANDLE_BASE_LEN = 8 + 149;
+// SPL Token account: mint(32) | owner(32) | amount(u64 LE, 8) | ...
+export const TOKEN_ACCOUNT_MIN_LEN = 72;
+// SPL Token mint: mint_authority COption(4+32) | supply(u64 LE, 8) @36 | ...
+const MINT_SUPPLY_OFFSET = 36;
+const MINT_MIN_LEN = MINT_SUPPLY_OFFSET + 8;
+// The registry mints handle NFTs with the legacy SPL Token program, so every
+// token account for a handle mint is owned by it.
+export const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export function readI64(data, offset) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(offset, true);
+}
+export function readU64(data, offset) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigUint64(offset, true);
+}
+export function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Parse the `Handle` fields readers need. Port of `parse_handle` in
+ * tools/api — sequential, because `recovery` / `recovery_target` are
+ * `Option<Pubkey>` (Borsh: tag byte, then 32 bytes when `Some`) and shift
+ * `registered_at`. The NFT mint is read at the fixed base boundary, not the
+ * sequential position.
+ *
+ *   disc(8) name(32) name_len(1) owner(32) handle_type(1)
+ *   recovery: Option<Pubkey>  recovery_initiated_at: i64
+ *   recovery_target: Option<Pubkey>  registered_at: i64  bump(1)
+ *   [at 8+149: nft tag(1) mint(32)]
+ */
+export function parseHandleAccount(data) {
+    if (data.length < HANDLE_BASE_LEN)
+        return null;
+    const nameLen = Math.min(data[40], 32);
+    const name = new TextDecoder().decode(data.slice(8, 8 + nameLen));
+    const owner = data.slice(HANDLE_OWNER_OFFSET, HANDLE_OWNER_OFFSET + 32);
+    let pos = 73 + 1; // owner end + handle_type(1)
+    // recovery: Option<Pubkey>
+    if (pos >= data.length)
+        return null;
+    pos += 1 + (data[pos] === 1 ? 32 : 0);
+    pos += 8; // recovery_initiated_at
+    // recovery_target: Option<Pubkey>
+    if (pos >= data.length)
+        return null;
+    pos += 1 + (data[pos] === 1 ? 32 : 0);
+    if (pos + 8 > data.length)
+        return null;
+    const registeredAt = readI64(data, pos);
+    const nftMint = data.length >= HANDLE_BASE_LEN + 33 && data[HANDLE_BASE_LEN] === 1
+        ? data.slice(HANDLE_BASE_LEN + 1, HANDLE_BASE_LEN + 33)
+        : null;
+    return { name, owner, registeredAt, nftMint };
+}
+/** Build the RPC plumbing every reader in this package shares. */
+export function makeAccountReader(rpcUrl, fetchImpl) {
+    const doFetch = fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+        throw new Error("No fetch available; pass fetchImpl in the config");
+    }
+    async function rpc(method, params) {
+        let res;
+        try {
+            res = await doFetch(rpcUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+            });
+        }
+        catch (e) {
+            throw new ResolveError("rpc-error", `RPC request failed: ${String(e)}`);
+        }
+        if (!res.ok) {
+            throw new ResolveError("rpc-error", `RPC returned HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new ResolveError("rpc-error", body.error.message ?? "RPC error");
+        }
+        return body.result;
+    }
+    async function accountInfo(address) {
+        const result = (await rpc("getAccountInfo", [
+            address,
+            { encoding: "base64", commitment: "confirmed" },
+        ]));
+        const value = result?.value;
+        if (!value)
+            return null;
+        const b64 = value.data[0];
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return { data: out, owner: value.owner };
+    }
+    async function accountData(address) {
+        return (await accountInfo(address))?.data ?? null;
+    }
+    return { rpc, accountInfo, accountData };
+}
+/**
+ * Current holder of a tokenized handle: the owner of the single token
+ * account holding the handle's NFT (supply 1, decimals 0). Never falls back
+ * to `Handle.owner` — after the NFT changes hands that field names the
+ * previous owner, and paying it is the exact failure this SDK exists to
+ * prevent.
+ *
+ * Parity with the program's `require_current_authority` (and the
+ * resolver's `reverse()`): the program recognises the holder as the name's
+ * authority only when the NFT sits in the holder's **associated token
+ * account** for the mint. A holder whose NFT is parked elsewhere (an
+ * auxiliary account, a program escrow) still controls the token, so the
+ * address is returned — but as `unverified`, because the registry will not
+ * let that address act for the name until the NFT is back in its ATA.
+ *
+ * A burned NFT (mint supply 0) is `not-found` with reason `nft-burned`: the
+ * name has no holder, and no one — least of all the stale `owner` — may be
+ * paid for it. Any other failure to find the holder is an `rpc-error`.
+ */
+export async function nftHolder(reader, wasm, canonical, mint, input) {
+    const mintKey = encodeBase58(mint);
+    const largest = (await reader.rpc("getTokenLargestAccounts", [
+        mintKey,
+        { commitment: "confirmed" },
+    ]));
+    const holders = (largest?.value ?? []).filter((a) => a.amount === "1");
+    if (holders.length !== 1) {
+        const m = await reader.accountInfo(mintKey);
+        if (m &&
+            m.owner === SPL_TOKEN_PROGRAM &&
+            m.data.length >= MINT_MIN_LEN &&
+            readU64(m.data, MINT_SUPPLY_OFFSET) === 0n) {
+            throw new ResolveError("not-found", `@${canonical}'s NFT has been burned — the name has no holder`, input, "nft-burned");
+        }
+        throw new ResolveError("rpc-error", `@${canonical} is tokenized but its NFT has no single holder`, input);
+    }
+    const holdingAccount = holders[0].address;
+    const t = await reader.accountInfo(holdingAccount);
+    if (!t ||
+        t.owner !== SPL_TOKEN_PROGRAM ||
+        t.data.length < TOKEN_ACCOUNT_MIN_LEN ||
+        !bytesEqual(t.data.slice(0, 32), mint) ||
+        readU64(t.data, 64) !== 1n) {
+        throw new ResolveError("rpc-error", `@${canonical} is tokenized but its NFT holder account is malformed`, input);
+    }
+    const holder = t.data.slice(32, 64);
+    const ata = wasm.deriveAssociatedTokenAccount(holder, mint);
+    const inAta = ata !== null && encodeBase58(ata) === holdingAccount;
+    return { address: encodeBase58(holder), verification: inAta ? "verified" : "unverified" };
+}

package/dist/attestation.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Domain/social verification attestations (`Attestation` accounts, #7379) —
+ * read WITH the universal staleness rule from docs/record-trust.md
+ * structurally enforced, plus instruction builders for `set_attestor` /
+ * `create_attestation` / `close_attestation`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return the
+ * transport-neutral {@link BuiltInstruction} `delegate.ts` defines; PDAs are
+ * NOT derived here (see delegate.ts's module docs for why — derive
+ * `["attestation", handlePda, kindByte]` / `["attestor_config"]` with your
+ * runtime's canonical `findProgramAddress`).
+ *
+ * # What an attestation proves — and, honestly, what it does not
+ *
+ * An `Attestation` proves exactly one statement: **"the key configured in
+ * `AttestorConfig` — the x1id review process — attested this evidence at
+ * time `attestedAt`."** It is NOT a trustless proof of domain or social
+ * control: the verification (DNS lookup, social-post check, human review)
+ * happens OFF-chain, and the chain records only that the attestor key signed
+ * off on it. That key is admin-rotatable, so the trust anchor is "whoever
+ * the registry admin currently designates" — rotatable-key trust, not
+ * trustlessness. Consumers needing stronger guarantees must not render an
+ * attestation as more than it is.
+ *
+ * # Verified = ONE live attestation of EITHER kind
+ *
+ * Per the #7145 decision (a single strong signal is enough — requiring two
+ * would reject Nike proving control of nike.com), a handle is "verified"
+ * when at least one NON-STALE attestation of either kind exists; `kind`
+ * records which signal proved it. {@link isHandleVerified} implements
+ * exactly this.
+ *
+ * # Why every function here demands `registeredAt` — epoch-bound, no TTL
+ *
+ * Attestations do not expire on a timer (owner decision 2026-09-03); they
+ * are invalidated by OWNERSHIP EPOCH. A `Handle`'s address is
+ * `["handle", name]` — a pure function of the name — so release +
+ * re-register lands the new registration at the SAME pubkey, and the
+ * previous owner's attestation is physically attached to the new owner's
+ * name with no action by anyone. The mandatory read-side rule
+ * (docs/record-trust.md, the universal rule):
+ *
+ *     attestation.attested_at >= handle.registered_at
+ *
+ * An attestation that fails it belongs to a previous, unrelated owner and
+ * must never be rendered as verifying the current one. Like `records.ts`,
+ * there is deliberately no way to decode or fetch an attestation through
+ * this module without the handle's `registered_at` in hand. (The one
+ * 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.)
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+/** Seed prefix of an attestation PDA: `["attestation", handlePda, kindByte]`. */
+export declare const ATTESTATION_SEED = "attestation";
+/** Seed of the attestor-config singleton PDA: `["attestor_config"]`. */
+export declare const ATTESTOR_CONFIG_SEED = "attestor_config";
+/** `Attestation.kind` — domain control proven (DNS TXT challenge). */
+export declare const ATTESTATION_KIND_DNS = 0;
+/** `Attestation.kind` — social-account control proven. */
+export declare const ATTESTATION_KIND_SOCIAL = 1;
+/** Anchor account discriminator: `sha256("account:Attestation")[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 ATTESTATION_DISCRIMINATOR: Uint8Array;
+/** Anchor account discriminator: `sha256("account:AttestorConfig")[0..8]`. */
+export declare const ATTESTOR_CONFIG_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:set_attestor")[0..8]`. */
+export declare const SET_ATTESTOR_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:create_attestation")[0..8]`. */
+export declare const CREATE_ATTESTATION_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:close_attestation")[0..8]`. */
+export declare const CLOSE_ATTESTATION_DISCRIMINATOR: Uint8Array;
+/** `Attestation` account size — every field is fixed-width, so unlike a
+ *  `Handle` the account is exactly this long:
+ *  disc(8) + handle(32) + kind(1) + evidence_hash(32) + attested_at(8)
+ *  + attestor(32) + bump(1). */
+export declare const ATTESTATION_LEN = 114;
+/** `AttestorConfig` account size: disc(8) + attestor(32) + bump(1). */
+export declare const ATTESTOR_CONFIG_LEN = 41;
+/** Which verification signal an attestation `kind` byte names, or null for a
+ *  kind this SDK does not know (future program versions may add kinds). */
+export declare function attestationKindName(kind: number): "dns" | "social" | null;
+/** A decoded verification attestation, staleness already judged. */
+export interface HandleAttestation {
+    /** The Attestation account's address, base58. */
+    readonly account: string;
+    /** The Handle account this attestation is for, base58. */
+    readonly handle: string;
+    /** Raw kind byte (0 = dns, 1 = social). */
+    readonly kind: number;
+    /** Human name for `kind`, or null for an unknown kind. */
+    readonly kindName: "dns" | "social" | null;
+    /** `sha256` commitment to the off-chain verdict-inputs bundle. */
+    readonly evidenceHash: Uint8Array;
+    /** Unix seconds the attestation was (last) stamped. */
+    readonly attestedAt: bigint;
+    /** The attestor key that signed the stamp, base58 — a historical fact,
+     *  not re-checked against the current `AttestorConfig`. */
+    readonly attestor: string;
+    /**
+     * The rule docs/record-trust.md mandates: this attestation only vouches
+     * for the current owner if `attested_at >= handle.registered_at`. A stale
+     * attestation belongs to a previous, unrelated owner of the same name and
+     * must never be rendered as verifying the current one.
+     */
+    readonly stale: boolean;
+}
+/**
+ * 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).
+ *
+ * Returns null for anything that is not an Attestation: wrong length or
+ * wrong discriminator.
+ */
+export declare function decodeAttestation(raw: Uint8Array, account: string, registeredAt: bigint): HandleAttestation | null;
+/** The attestations that vouch for the CURRENT owner — `stale` ones
+ *  excluded. This is the list to judge verification from. */
+export declare function liveAttestations(attestations: readonly HandleAttestation[]): HandleAttestation[];
+/**
+ * The #7145 verified rule: a handle is verified when at least ONE non-stale
+ * attestation of EITHER kind exists (a single strong signal is enough; the
+ * surviving `kindName`s say which signals proved it).
+ */
+export declare function isHandleVerified(attestations: readonly HandleAttestation[]): boolean;
+/**
+ * Fetch every Attestation account of a handle — one `getProgramAccounts`
+ * call, filtered by the RPC on size (114), the Attestation 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) —
+ * the exact shape of `fetchRecords`. Scoping the scan to the registry
+ * program id also IS the ownership check.
+ *
+ * `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}.
+ */
+export declare function fetchAttestations(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint): Promise<HandleAttestation[]>;
+export interface SetAttestorParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The registry admin (`Config.admin`). Signer; also pays the one-time
+     *  `AttestorConfig` init. */
+    readonly admin: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The `["attestor_config"]` PDA — derive per the module docs. */
+    readonly attestorConfig: AddressLike;
+    /** The key being granted attestation-signing authority. */
+    readonly attestor: AddressLike;
+}
+/**
+ * Build `set_attestor` — admin-only: initialize or rotate the attestor key.
+ * Rotation does not void existing attestations (they record their signer as
+ * a historical fact); revoking a bad key's output is `close_attestation`.
+ */
+export declare function buildSetAttestorIx(p: SetAttestorParams): BuiltInstruction;
+export interface CreateAttestationParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The configured attestor. Signer; pays the attestation's rent on first
+     *  stamp. */
+    readonly attestor: AddressLike;
+    /** The `["attestor_config"]` PDA. */
+    readonly attestorConfig: AddressLike;
+    /** The `["handle", name]` PDA being attested (must be registered). */
+    readonly handle: AddressLike;
+    /** The `["attestation", handle, kindByte]` PDA — derive per the module
+     *  docs, with the SAME kind byte passed below. */
+    readonly attestation: AddressLike;
+    /** {@link ATTESTATION_KIND_DNS} or {@link ATTESTATION_KIND_SOCIAL}. */
+    readonly kind: number;
+    /** `sha256` of the off-chain verdict-inputs bundle (32 bytes) — a
+     *  commitment, never the raw evidence. */
+    readonly evidenceHash: Uint8Array;
+}
+/**
+ * Build `create_attestation` — attestor-only: stamp (or re-stamp,
+ * re-deriving `attested_at` from the Clock and replacing the evidence hash)
+ * the (handle, kind) attestation.
+ */
+export declare function buildCreateAttestationIx(p: CreateAttestationParams): BuiltInstruction;
+export interface CloseAttestationParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The current attestor OR the admin. Signer. */
+    readonly signer: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The `["attestor_config"]` PDA. */
+    readonly attestorConfig: AddressLike;
+    /** The attestation account being closed. No Handle account is needed —
+     *  the program re-derives the seeds from the attestation's own stored
+     *  fields, so a stale attestation stranded by a released handle stays
+     *  revocable. */
+    readonly attestation: AddressLike;
+    /** Receives the closed account's rent — any account the caller chooses. */
+    readonly recipient: AddressLike;
+}
+/**
+ * Build `close_attestation` — revoke: close the account, rent to
+ * `recipient`. Attestor- or admin-signed (the admin path is the cleanup for
+ * a rotated-away key's output).
+ */
+export declare function buildCloseAttestationIx(p: CloseAttestationParams): BuiltInstruction;