@x1id/resolve 0.3.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fortiblox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -257,6 +257,23 @@ const ix = buildCreateSubnameIx({
 // add `ix` to a transaction, sign with payer + owner, send.
 ```
 
+**Register a handle** (pays whatever the on-chain ramp charges as of the
+landing slot — there is no client-supplied price):
+
+```ts
+import { buildRegisterIx, fetchConfigTreasury, HandleType } from "@x1id/resolve";
+
+const treasury = await fetchConfigTreasury(rpc, configAccount); // Config.treasury, read fresh
+const ix = buildRegisterIx({
+  programId, payer, owner,
+  config: configAccount,       // the ["config"] PDA
+  treasury,
+  handle,                      // the ["handle", name] PDA — must be unregistered
+  name: "payday-bot",
+  handleType: HandleType.Agent,
+});
+```
+
 **Gift a handle** (prepaid voucher; the recipient claims it later):
 
 ```ts
@@ -281,13 +298,123 @@ Also shipped, same build → sign → relay shape:
 | Name lock / timelocked unlock | `buildLockHandleIx`, `buildInitiateUnlockIx`, `buildCompleteUnlockIx`, `buildCancelUnlockIx` |
 | Record-write delegation | `buildSetRecordDelegateIx`, `buildRevokeRecordDelegateIx` |
 | Typed text records (website / avatar / socials) | `buildCreateTextRecordIx`, `buildUpdateTextRecordIx`, `buildCloseTextRecordIx` |
+| Register a handle | `buildRegisterIx` (+ `fetchConfigTreasury`) |
+| Verify a non-SVM address record | `buildCreateRecordIx`, `buildVerifyRecordEthIx`, `buildVerifyRecordSvmIx`, `buildVerifyRecordBtcIx` (+ `buildRecordChallenge`, `splitEthSignature`, `splitBtcSignature`) — see [Verifying a non-SVM address record](#verifying-a-non-svm-address-record) |
 | Domain / social attestations | `buildCreateAttestationIx`, `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`) |
+| Agent records (identity, manifest, x402 hints) | `validateManifest`, `agentVerificationLevel`, `x402AcceptsFromManifest`, `agentTextRecords` — see [Agent records](#agent-records) below |
 | 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.
 
+## Agent records
+
+An `@handle` can identify, describe, and get paid as an AI agent —
+conventions on top of the existing primitives above (`HandleType.Agent`,
+text records, address records, attestations), **no new on-chain account
+family**. Full design: [`docs/agent-records.md`](../docs/agent-records.md).
+
+```ts
+import {
+  AGENT_RECORD_KEYS,
+  agentTextRecords,
+  validateManifest,
+  agentVerificationLevel,
+  x402AcceptsFromManifest,
+} from "@x1id/resolve";
+
+// after fetching + liveTextRecords(...) for the handle:
+const agent = agentTextRecords(textRecords);
+if (agent.manifest) {
+  const raw = await fetch(agent.manifest).then((r) => r.json());
+  const result = validateManifest(raw, {
+    expectedName: "payday-bot",
+    expectedHandlePda: handleAccount,
+    expectedNetwork: "testnet",
+    addressRecords: liveRecords(records), // "the chain wins" cross-check
+  });
+  if (result.ok) {
+    const level = agentVerificationLevel({
+      handleType,
+      agentRecords: agent,
+      liveAttestations: liveAttestations(attestations),
+      manifest: result.manifest,
+    }); // 0, 1, or null — L2 ("pay-to confirmed") is a live HTTP fact, not implemented here; see the MCP server
+    const hints = x402AcceptsFromManifest(result.manifest, { payTo: verifiedAddress });
+  }
+}
+```
+
+`validateManifest` never trusts a manifest's own claims over the chain: a
+`payment.addresses[]` entry claiming `verified: true` is rejected outright if
+the supplied on-chain records disagree. `agentVerificationLevel` reports only
+the highest level it actually checked — L1 requires the manifest's claimed
+attestation to match a *live* one, never assumed from presence alone.
+
+## Verifying a non-SVM address record
+
+Prove control of an ETH, BTC, or another SVM address so its `Record` gets
+`verified: true`. On-chain, the program itself recovers the address from
+the signature — this SDK never derives or checks an address client-side,
+it just builds the challenge and packages the wallet's signature.
+
+```ts
+import {
+  buildRecordChallenge,
+  buildCreateRecordIx,
+  buildVerifyRecordEthIx,
+  splitEthSignature,
+} from "@x1id/resolve";
+
+// 1. create the (unverified) record
+const createIx = buildCreateRecordIx({
+  programId, payer, owner, handle, record,
+  coinType: 60, // ETH, per SLIP-44
+  value: ethAddressBytes,
+});
+
+// 2. build the challenge and have the wallet sign it (personal_sign)
+const challenge = buildRecordChallenge("alice", 60, registeredAt, "someNonce123");
+const sig65 = await wallet.signMessage(challenge); // 65 raw bytes: r || s || v
+
+// 3. verify
+const { signature, recoveryId } = splitEthSignature(sig65);
+const verifyIx = buildVerifyRecordEthIx({
+  programId, owner, handle, record,
+  nonce: "someNonce123", signature, recoveryId,
+});
+```
+
+`buildVerifyRecordSvmIx` (the claimed address just co-signs, no challenge
+needed) and `buildVerifyRecordBtcIx` + `splitBtcSignature` (BIP-137, mainnet
+compressed-P2PKH or bech32/P2WPKH only) follow the same shape.
+
+## x402 payments
+
+An agent gets paid over HTTP via [x402](https://github.com/x402-foundation/x402)'s
+`"exact"` SVM scheme. Full design (including how transactions actually get
+built/verified — that needs real Solana parsing, so it lives in the
+[x1id MCP server](../mcp), not here): [`docs/x402.md`](../docs/x402.md).
+
+```ts
+import { buildX402Requirements, X1_TESTNET_NETWORK } from "@x1id/resolve";
+
+// server-side: one accepts[] entry for a 402 response
+const requirements = buildX402Requirements({
+  payTo: sellerAddress,
+  asset: usdcMint,
+  amount: "1000000", // smallest units, decimal string
+  buyer: buyerAddress, // x1id v1 is self-sponsored: buyer pays their own fee, no facilitator
+  memo: "invoice-42",
+});
+```
+
+This package only builds the requirements object — it does not build, sign,
+or verify a transaction (that needs `@solana/web3.js`, deliberately kept out
+of this zero-dependency package). Use the MCP server's `prepare_x402_payment`
+/ `verify_x402_payment` tools for that.
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:
@@ -412,7 +539,7 @@ attached, and this file is the accurate statement.)
 ## Links
 
 - Home & docs: **[x1id.io](https://x1id.io)**
-- Developer docs: **[docs.fortiblox.com/docs/x1id](https://docs.fortiblox.com/docs/x1id)**
+- Developer docs: **[docs.x1id.io](https://docs.x1id.io)**
 - Questions & issues: [x1id.io](https://x1id.io) — contact links in the footer
 
 ## License

package/dist/accounts.d.ts

@@ -27,6 +27,13 @@ export interface ParsedHandle {
      * docs/record-trust.md.
      */
     readonly registeredAt: bigint;
+    /**
+     * `Handle.records_cleared_at` (0 if never cleared) — set by `clear_records`
+     * (#8139). Every per-handle record/text-record/attestation must ALSO be
+     * judged stale when `updated_at < recordsClearedAt`, alongside (not instead
+     * of) the `registeredAt` epoch rule — see docs/record-trust.md.
+     */
+    readonly recordsClearedAt: bigint;
     /** Set when the handle is tokenized (NFT extension present). */
     readonly nftMint: Uint8Array | null;
 }

package/dist/accounts.js

@@ -26,6 +26,12 @@ const HANDLE_OWNER_OFFSET = 41;
 // mirrors `Handle::NFT_EXT_OFFSET` in the program and `HANDLE_BASE_LEN` in
 // tools/api.
 const HANDLE_BASE_LEN = 8 + 149;
+// `records_cleared_at` extension (`Handle::RECORDS_CLEARED_EXT_OFFSET`, #8139):
+// an i64 LE the owner bumps via `clear_records` to bulk-invalidate every
+// record/text-record/attestation without transferring the handle. Read
+// leniently — a short or zeroed account means "never cleared" (0), same
+// convention as every other Handle extension region.
+const RECORDS_CLEARED_EXT_OFFSET = 229;
 // 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 | ...
@@ -82,7 +88,8 @@ export function parseHandleAccount(data) {
     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 };
+    const recordsClearedAt = data.length >= RECORDS_CLEARED_EXT_OFFSET + 8 ? readI64(data, RECORDS_CLEARED_EXT_OFFSET) : 0n;
+    return { name, owner, registeredAt, recordsClearedAt, nftMint };
 }
 /** Build the RPC plumbing every reader in this package shares. */
 export function makeAccountReader(rpcUrl, fetchImpl) {

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

@@ -50,6 +50,15 @@
  * documented blind spot is shared with `Handle.owner`/`Primary`/
  * `RecordDelegate`: a bearer-NFT marketplace trade bumps no epoch, so the
  * attestation keeps reading live until the attestor re-reviews or revokes.)
+ *
+ * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
+ *
+ * `clear_records` lets an owner bulk-invalidate every record RIGHT NOW,
+ * without a transfer — its own doc comment (lib.rs) names attestations
+ * explicitly alongside records/text-records as sharing this epoch rule. The
+ * same functions therefore also demand the handle's `recordsClearedAt` (0 if
+ * never cleared, from `ParsedHandle`), and an attestation is `stale` when
+ * EITHER `attested_at < registeredAt` OR `attested_at < recordsClearedAt`.
  */
 import type { AddressLike, BuiltInstruction } from "./delegate.js";
 import type { RpcFn } from "./accounts.js";
@@ -113,13 +122,15 @@ export interface HandleAttestation {
  * Decode one Attestation account.
  *
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
- * caller from the Handle account — it decides `stale`. There is
- * intentionally no overload without it (see the module docs).
+ * caller from the Handle account — it decides `stale`. `recordsClearedAt` is
+ * that same Handle's `recordsClearedAt` (0 if never cleared, #8139), a
+ * SECOND independent staleness anchor. There is intentionally no overload
+ * without either (see the module docs).
  *
  * Returns null for anything that is not an Attestation: wrong length or
  * wrong discriminator.
  */
-export declare function decodeAttestation(raw: Uint8Array, account: string, registeredAt: bigint): HandleAttestation | null;
+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[];
@@ -139,12 +150,13 @@ export declare function isHandleVerified(attestations: readonly HandleAttestatio
  *
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
- * is no variant of this function without it. Every attestation is returned,
- * stale ones flagged, so an owner surface can show what a previous
- * registration left behind; anything that renders a verified badge takes
- * {@link isHandleVerified} / {@link liveAttestations}.
+ * is no variant of this function without it. `recordsClearedAt` is that same
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Every attestation is returned, stale ones flagged, so an owner surface can
+ * show what a previous registration left behind; anything that renders a
+ * verified badge takes {@link isHandleVerified} / {@link liveAttestations}.
  */
-export declare function fetchAttestations(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint): Promise<HandleAttestation[]>;
+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;