@x1id/resolve 0.2.1 → 0.6.0

package/dist/agent.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Agent records — identify, describe, and verify an `@handle` operating as
+ * an AI agent. See `docs/agent-records.md` for the full design and the
+ * honest account of what each verification level does and does not prove.
+ *
+ * This is conventions on EXISTING primitives, not a new account family:
+ * `HandleType.Agent` (already on-chain), well-known `TextRecord` keys
+ * (`textRecords.ts`, #7376), address `Record`s (`records.ts`), and
+ * `Attestation` (`attestation.ts`, #7379). Nothing here requires a program
+ * change.
+ *
+ * Hand-rolled like the rest of this package — no schema-interpreter
+ * dependency, no `@solana/web3.js` import. `validateManifest` is plain
+ * field checks, matching how `records.ts`/`textRecords.ts`/`attestation.ts`
+ * hand-decode rather than lean on a generic library.
+ *
+ * # L2 ("pay-to confirmed") is deliberately NOT implemented here
+ *
+ * It's a live HTTP fact against an arbitrary third-party host — forcing a
+ * network call inside a library used in contexts that may not want one.
+ * That check (`probe402`) belongs in a service that's already making
+ * network calls on the caller's behalf — tracked as the x1id MCP server,
+ * WP #8133. `AgentVerificationLevel` still names level 2 so every surface
+ * that reports a level shares one vocabulary.
+ */
+import type { HandleTextRecord } from "./textRecords.js";
+import type { HandleAttestation } from "./attestation.js";
+import type { HandleRecord } from "./records.js";
+/** The six well-known `TextRecord` keys an agent handle may set. Every
+ *  value must be `https://` EXCEPT `manifest`, which may also be
+ *  `ipfs://<cid>` — see {@link checkAgentUrl}. */
+export declare const AGENT_RECORD_KEYS: Readonly<{
+    readonly manifest: "agent.manifest";
+    readonly x402: "agent.x402";
+    readonly mcp: "agent.mcp";
+    readonly a2a: "agent.a2a";
+    readonly attestation: "agent.attestation";
+    readonly capabilities: "agent.capabilities";
+}>;
+export type AgentEndpointType = "x402" | "mcp" | "a2a" | "http";
+/** `agent.manifest` v1 (`docs/agent-records.md` §3), as accepted by
+ *  {@link validateManifest}. */
+export interface AgentManifest {
+    readonly x1id: {
+        readonly version: 1;
+        readonly name: string;
+        readonly network: "testnet" | "mainnet";
+        /** Base58 address of the `Handle` PDA — the uniqueness anchor. */
+        readonly handle: string;
+    };
+    readonly identity?: {
+        /** Base58 address of a non-stale `Attestation` account on this handle
+         *  (kind DNS or SOCIAL). See `docs/agent-records.md` §4 for what this
+         *  does and does not prove — it is NOT an agent-identity-registry
+         *  ownership check, that concept has no SVM equivalent yet. */
+        readonly attestation?: string;
+        readonly description?: string;
+    };
+    readonly endpoints?: readonly {
+        readonly type: AgentEndpointType;
+        readonly url: string;
+    }[];
+    readonly capabilities?: {
+        readonly schema?: string;
+        readonly url: string;
+    };
+    readonly payment?: {
+        readonly addresses?: readonly {
+            readonly coinType: number;
+            readonly address: string;
+            readonly verified?: boolean;
+        }[];
+        readonly x402?: {
+            readonly network: string;
+            readonly asset?: string;
+            readonly scheme?: string;
+            readonly facilitator?: string;
+            readonly extra?: Readonly<Record<string, unknown>>;
+        };
+    };
+}
+/** URL rule (`docs/agent-records.md` §2): every URL field is `https://`
+ *  ONLY, except `agent.manifest`'s own record value, which may also be
+ *  `ipfs://<cid>` (`allowIpfs`). */
+export declare function checkAgentUrl(url: string, allowIpfs?: boolean): boolean;
+export interface ValidateManifestOptions {
+    /** The handle name this manifest is being read FOR (no `@`). Required —
+     *  a manifest that doesn't match is discarded, never partially trusted. */
+    readonly expectedName: string;
+    /** The `Handle` PDA address (base58) this manifest is being read FOR. */
+    readonly expectedHandlePda: string;
+    readonly expectedNetwork: "testnet" | "mainnet";
+    /** The handle's live, non-stale address records — when supplied, every
+     *  `payment.addresses[]` entry claiming `verified: true` is cross-checked
+     *  against them and rejected if the chain disagrees ("the chain wins",
+     *  `docs/agent-records.md` §3). Omit to skip this cross-check (shape-only
+     *  validation). */
+    readonly addressRecords?: readonly HandleRecord[];
+}
+export type ManifestValidationError = {
+    readonly code: "not-an-object";
+} | {
+    readonly code: "missing-field";
+    readonly field: string;
+} | {
+    readonly code: "bad-version";
+} | {
+    readonly code: "name-mismatch";
+} | {
+    readonly code: "handle-mismatch";
+} | {
+    readonly code: "network-mismatch";
+} | {
+    readonly code: "bad-url";
+    readonly field: string;
+} | {
+    readonly code: "bad-attestation-address";
+} | {
+    readonly code: "bad-payment-address";
+} | {
+    readonly code: "overclaims-verified";
+    readonly coinType: number;
+};
+export type ManifestValidationResult = {
+    readonly ok: true;
+    readonly manifest: AgentManifest;
+} | {
+    readonly ok: false;
+    readonly errors: readonly ManifestValidationError[];
+};
+/**
+ * Validate a manifest's shape AND, when `addressRecords` is supplied, its
+ * agreement with the chain. Never trusts a claim the manifest makes about
+ * itself over what the caller already knows to be true on-chain.
+ */
+export declare function validateManifest(raw: unknown, opts: ValidateManifestOptions): ManifestValidationResult;
+/** Pick the agent-related well-known keys out of a handle's live text
+ *  records (pass the output of `liveTextRecords` — stale entries excluded
+ *  already, matching every other read path's convention). */
+export declare function agentTextRecords(records: readonly HandleTextRecord[]): Partial<Record<keyof typeof AGENT_RECORD_KEYS, string>>;
+/** L2 is intentionally never returned here — see the module docs. `null`
+ *  means "not even declared." */
+export type AgentVerificationLevel = 0 | 1 | null;
+export interface AgentVerificationInput {
+    readonly handleType: number;
+    /** `agentTextRecords(...)`'s output for this handle. */
+    readonly agentRecords: Partial<Record<keyof typeof AGENT_RECORD_KEYS, string>>;
+    /** This handle's live (non-stale) attestations — `liveAttestations(...)`. */
+    readonly liveAttestations: readonly HandleAttestation[];
+    /** The parsed manifest, if `agent.manifest` was fetched and validated.
+     *  Omit if the manifest wasn't fetched — L1 is then reported as
+     *  "not checked" (null), never "failed", per the reporting rule below. */
+    readonly manifest?: AgentManifest;
+}
+/**
+ * L0/L1, computed from data the caller already has (no RPC calls in this
+ * function — see the module docs for why L2 requires a live network call
+ * and lives elsewhere).
+ *
+ * A reader reports only the highest level it actually checked. If
+ * `manifest` wasn't supplied, L1 is reported `null` ("not checked"), not
+ * `0` ("failed") — the same discipline ArcNS's reference design uses.
+ */
+export declare function agentVerificationLevel(input: AgentVerificationInput): AgentVerificationLevel;
+export interface X402AcceptHint {
+    readonly scheme: string;
+    readonly network: string;
+    readonly resource: string;
+    readonly asset?: string;
+    readonly payTo?: string;
+    readonly facilitator?: string;
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Turn a validated manifest into x402-shaped `accepts[]` hints. NEVER
+ * authoritative — the resource's own live 402 response always wins; this is
+ * a pre-flight convenience so a caller doesn't have to probe every endpoint
+ * just to learn the shape it should expect.
+ *
+ * `opts.payTo`, when supplied, is preferred over anything the manifest
+ * claims for itself (chain-verified address beats a self-reported mirror).
+ * Returns `[]` for an agent with no `x402` endpoints.
+ */
+export declare function x402AcceptsFromManifest(manifest: AgentManifest, opts?: {
+    readonly payTo?: string;
+}): readonly X402AcceptHint[];

package/dist/agent.js

@@ -0,0 +1,213 @@
+/**
+ * Agent records — identify, describe, and verify an `@handle` operating as
+ * an AI agent. See `docs/agent-records.md` for the full design and the
+ * honest account of what each verification level does and does not prove.
+ *
+ * This is conventions on EXISTING primitives, not a new account family:
+ * `HandleType.Agent` (already on-chain), well-known `TextRecord` keys
+ * (`textRecords.ts`, #7376), address `Record`s (`records.ts`), and
+ * `Attestation` (`attestation.ts`, #7379). Nothing here requires a program
+ * change.
+ *
+ * Hand-rolled like the rest of this package — no schema-interpreter
+ * dependency, no `@solana/web3.js` import. `validateManifest` is plain
+ * field checks, matching how `records.ts`/`textRecords.ts`/`attestation.ts`
+ * hand-decode rather than lean on a generic library.
+ *
+ * # L2 ("pay-to confirmed") is deliberately NOT implemented here
+ *
+ * It's a live HTTP fact against an arbitrary third-party host — forcing a
+ * network call inside a library used in contexts that may not want one.
+ * That check (`probe402`) belongs in a service that's already making
+ * network calls on the caller's behalf — tracked as the x1id MCP server,
+ * WP #8133. `AgentVerificationLevel` still names level 2 so every surface
+ * that reports a level shares one vocabulary.
+ */
+import { X1_TESTNET_NETWORK } from "./x402.js";
+// ---------------------------------------------------------------------------
+// Well-known text-record keys
+// ---------------------------------------------------------------------------
+/** The six well-known `TextRecord` keys an agent handle may set. Every
+ *  value must be `https://` EXCEPT `manifest`, which may also be
+ *  `ipfs://<cid>` — see {@link checkAgentUrl}. */
+export const AGENT_RECORD_KEYS = Object.freeze({
+    manifest: "agent.manifest",
+    x402: "agent.x402",
+    mcp: "agent.mcp",
+    a2a: "agent.a2a",
+    attestation: "agent.attestation",
+    capabilities: "agent.capabilities",
+});
+const HTTPS_RE = /^https:\/\/[^\s@/]+(\/[^\s]*)?$/;
+const IPFS_RE = /^ipfs:\/\/[^\s]+$/;
+const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** URL rule (`docs/agent-records.md` §2): every URL field is `https://`
+ *  ONLY, except `agent.manifest`'s own record value, which may also be
+ *  `ipfs://<cid>` (`allowIpfs`). */
+export function checkAgentUrl(url, allowIpfs = false) {
+    if (HTTPS_RE.test(url) && url.length <= 2048)
+        return true;
+    return allowIpfs && IPFS_RE.test(url);
+}
+/**
+ * Validate a manifest's shape AND, when `addressRecords` is supplied, its
+ * agreement with the chain. Never trusts a claim the manifest makes about
+ * itself over what the caller already knows to be true on-chain.
+ */
+export function validateManifest(raw, opts) {
+    const errors = [];
+    if (typeof raw !== "object" || raw === null) {
+        return { ok: false, errors: [{ code: "not-an-object" }] };
+    }
+    const m = raw;
+    const x1id = m.x1id;
+    if (typeof x1id !== "object" || x1id === null) {
+        return { ok: false, errors: [{ code: "missing-field", field: "x1id" }] };
+    }
+    if (x1id.version !== 1)
+        errors.push({ code: "bad-version" });
+    if (x1id.name !== opts.expectedName)
+        errors.push({ code: "name-mismatch" });
+    if (x1id.handle !== opts.expectedHandlePda)
+        errors.push({ code: "handle-mismatch" });
+    if (x1id.network !== opts.expectedNetwork)
+        errors.push({ code: "network-mismatch" });
+    const identity = m.identity;
+    if (identity !== undefined) {
+        const att = identity.attestation;
+        if (att !== undefined && (typeof att !== "string" || !BASE58_RE.test(att))) {
+            errors.push({ code: "bad-attestation-address" });
+        }
+    }
+    const endpoints = m.endpoints;
+    if (endpoints !== undefined) {
+        for (const e of endpoints) {
+            if (typeof e.url !== "string" || !checkAgentUrl(e.url, false)) {
+                errors.push({ code: "bad-url", field: "endpoints[].url" });
+            }
+        }
+    }
+    const capabilities = m.capabilities;
+    if (capabilities !== undefined) {
+        if (typeof capabilities.url !== "string" || !checkAgentUrl(capabilities.url, false)) {
+            errors.push({ code: "bad-url", field: "capabilities.url" });
+        }
+        if (capabilities.schema !== undefined &&
+            (typeof capabilities.schema !== "string" || !checkAgentUrl(capabilities.schema, false))) {
+            errors.push({ code: "bad-url", field: "capabilities.schema" });
+        }
+    }
+    const payment = m.payment;
+    if (payment !== undefined) {
+        const addresses = payment.addresses;
+        if (addresses !== undefined) {
+            for (const a of addresses) {
+                if (typeof a.address !== "string" || a.address.length === 0 || a.address.length > 128) {
+                    errors.push({ code: "bad-payment-address" });
+                    continue;
+                }
+                if (a.verified === true && opts.addressRecords) {
+                    // "The chain wins": a manifest claiming verified:true for a coin
+                    // type the chain doesn't actually verify (or that resolves to a
+                    // different address) is rejected outright, never trusted.
+                    const onChain = opts.addressRecords.find((r) => r.coinType === a.coinType && !r.stale);
+                    const chainVerified = onChain !== undefined && onChain.address === a.address && onChain.verified === true;
+                    if (!chainVerified)
+                        errors.push({ code: "overclaims-verified", coinType: a.coinType });
+                }
+            }
+        }
+        const x402 = payment.x402;
+        if (x402 !== undefined) {
+            if (typeof x402.network !== "string" || x402.network.length === 0) {
+                errors.push({ code: "missing-field", field: "payment.x402.network" });
+            }
+            if (x402.facilitator !== undefined &&
+                (typeof x402.facilitator !== "string" || !checkAgentUrl(x402.facilitator, false))) {
+                errors.push({ code: "bad-url", field: "payment.x402.facilitator" });
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, manifest: raw };
+}
+// ---------------------------------------------------------------------------
+// Reading agent text records off a handle's already-fetched records
+// ---------------------------------------------------------------------------
+/** Pick the agent-related well-known keys out of a handle's live text
+ *  records (pass the output of `liveTextRecords` — stale entries excluded
+ *  already, matching every other read path's convention). */
+export function agentTextRecords(records) {
+    const byKey = new Map(records.map((r) => [r.key, r.text]));
+    const out = {};
+    for (const [name, key] of Object.entries(AGENT_RECORD_KEYS)) {
+        const v = byKey.get(key);
+        if (v)
+            out[name] = v;
+    }
+    return out;
+}
+/** `HandleType.Agent`'s numeric value (matches `voucher.ts`'s
+ *  `HandleType.Agent`). Duplicated here (not imported) to keep this module
+ *  independent of `voucher.ts`'s import surface. */
+const HANDLE_TYPE_AGENT = 3;
+/**
+ * L0/L1, computed from data the caller already has (no RPC calls in this
+ * function — see the module docs for why L2 requires a live network call
+ * and lives elsewhere).
+ *
+ * A reader reports only the highest level it actually checked. If
+ * `manifest` wasn't supplied, L1 is reported `null` ("not checked"), not
+ * `0` ("failed") — the same discipline ArcNS's reference design uses.
+ */
+export function agentVerificationLevel(input) {
+    const declared = input.handleType === HANDLE_TYPE_AGENT || input.agentRecords.manifest !== undefined;
+    if (!declared)
+        return null;
+    if (input.manifest === undefined)
+        return 0;
+    const claimedAttestation = input.manifest.identity?.attestation;
+    if (claimedAttestation === undefined)
+        return 0;
+    const matches = input.liveAttestations.some((a) => a.account === claimedAttestation);
+    return matches ? 1 : 0;
+}
+/**
+ * Turn a validated manifest into x402-shaped `accepts[]` hints. NEVER
+ * authoritative — the resource's own live 402 response always wins; this is
+ * a pre-flight convenience so a caller doesn't have to probe every endpoint
+ * just to learn the shape it should expect.
+ *
+ * `opts.payTo`, when supplied, is preferred over anything the manifest
+ * claims for itself (chain-verified address beats a self-reported mirror).
+ * Returns `[]` for an agent with no `x402` endpoints.
+ */
+export function x402AcceptsFromManifest(manifest, opts) {
+    const x402Endpoints = (manifest.endpoints ?? []).filter((e) => e.type === "x402");
+    if (x402Endpoints.length === 0)
+        return [];
+    const x402 = manifest.payment?.x402;
+    // X1_TESTNET_NETWORK is the real, verified x402 network id (see x402.ts).
+    // Mainnet has no such id yet — X1 mainnet doesn't exist — so a manifest
+    // claiming network: "mainnet" without its own explicit x402.network gets
+    // an honestly-provisional placeholder rather than a fabricated genesis hash.
+    const network = x402?.network ?? (manifest.x1id.network === "testnet" ? X1_TESTNET_NETWORK : "x1:mainnet-unassigned");
+    const payTo = opts?.payTo ?? manifest.payment?.addresses?.[0]?.address;
+    return x402Endpoints.map((e) => {
+        const hint = {
+            scheme: x402?.scheme ?? "exact",
+            network,
+            resource: e.url,
+        };
+        if (x402?.asset !== undefined)
+            hint.asset = x402.asset;
+        if (payTo !== undefined)
+            hint.payTo = payTo;
+        if (x402?.facilitator !== undefined)
+            hint.facilitator = x402.facilitator;
+        if (x402?.extra !== undefined)
+            hint.extra = x402.extra;
+        return hint;
+    });
+}

package/dist/attestation.d.ts

@@ -0,0 +1,226 @@
+/**
+ * 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.)
+ *
+ * # `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 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`. `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 declare function decodeAttestation(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: 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. `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 declare function fetchAttestations(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: 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;