@x1id/resolve 0.15.0 → 0.16.0

package/README.md

@@ -12,7 +12,7 @@ answered, and a mixed shape is refused rather than guessed.
 import { createResolver, WasmResolver } from "@x1id/resolve";
 
 const wasm = await WasmResolver.fromBytes(/* the module bytes, see below */);
-const x1id = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
+const x1id = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz", wasm });
 
 const r = await x1id.resolve("@jack");
 // { name: "jack", namespace: "handle", address: "H8Fs…", chain: "X1",
@@ -23,11 +23,11 @@ await x1id.resolve("@jack.x1");    // throws ResolveError { code: "ambiguous" }
 await x1id.reverse("H8Fs…");       // "nike" — the address's primary @handle, or null
 ```
 
-> **Which RPC?** The `@handle` registry is deployed on **X1 testnet** today
-> (`https://rpc.testnet.x1.xyz`). X1NS domains live on **mainnet**
-> (`https://rpc.mainnet.x1.xyz`). Point the resolver at the chain that holds
-> the names you want; on an RPC where the registry is not deployed a handle is
-> an honest `not-found`, never a fabricated address.
+> **Which RPC?** The `@handle` registry and X1NS domains are both on **X1
+> mainnet** (`https://rpc.mainnet.x1.xyz`) — point the resolver there. X1
+> testnet (`https://rpc.testnet.x1.xyz`) runs the same program and the SDK
+> works against it identically for development. On an RPC where the registry
+> is not deployed a handle is an honest `not-found`, never a fabricated address.
 
 ## Where this code lives
 
@@ -64,7 +64,7 @@ const require = createRequire(import.meta.url);
 const wasmPath = require.resolve("@x1id/resolve/wasm/x1_resolve_wasm.wasm");
 const wasm = await WasmResolver.fromBytes(readFileSync(wasmPath));
 
-const x1id = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
+const x1id = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz", wasm });
 ```
 
 Node ≥ 20.6 can use `import.meta.resolve` instead of `createRequire`:
@@ -139,7 +139,7 @@ const wasm = await WasmResolver.fromBytes(/* module bytes */);
 const scopedHandleDeriver = await makeScopedHandleDeriver(web3);
 
 const x1id = createResolver({
-  rpcUrl: "https://rpc.testnet.x1.xyz",
+  rpcUrl: "https://rpc.mainnet.x1.xyz",
   wasm,
   scopedHandleDeriver,
 });
@@ -366,18 +366,30 @@ export async function POST(req: Request) {           // any server runtime with
 }
 ```
 
-Fail-closed by default (re-throws if the decision can't be obtained; pass
-`{ onError: "allow" }` to fail-open). `checkGate()` is the lower-level client for
-the full decision; pass a stored policy's `gp_…` id as the policy to reuse a named
-policy. The hosted check is keyed/metered — see `services/dev-api`'s README.
+Fail-closed by default (re-throws if the decision can't be obtained). `onError:
+"deny"` fails closed without throwing (clean `allowed: false`). `checkGate()` is
+the lower-level client for the full decision; pass a stored policy's `gp_…` id as
+the policy to reuse a named policy. The hosted check is keyed/metered — see
+`services/dev-api`'s README.
+
+> **⚠️ Never use `onError: "allow"` on a real gate.** It FAILS OPEN: on *any*
+> error — a network blip, a timeout, a 5xx, an auth failure, a malformed
+> response — it fabricates a `passed: true` decision and admits the caller
+> **unverified**. Anyone who can make your gate call fail (trivially: induce a
+> timeout) then bypasses the gate completely, so it is worse than no gate at all
+> for anything it protects — a route, a mint, an airdrop, a write, an allowlist.
+> It exists ONLY for soft, non-security personalization where a missing
+> verification must not degrade UX (e.g. optionally showing a "verified"
+> flourish). Using it logs a one-time `console.warn`. If the decision gates
+> anything, use the default `"throw"` or `"deny"`.
 
 ## What works today
 
 | | Status |
 |---|---|
 | 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 |
+| `@handle` resolution | ✅ **X1 mainnet** (and any RPC where the registry is deployed, incl. testnet) |
+| Reverse lookup | ✅ on-chain `@handle` primary with X1NS primary-domain fallback; X1NS results are `<domainAccount>.<tld>`, not a label |
 | 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` |
@@ -508,7 +520,7 @@ if (agent.manifest) {
   const result = validateManifest(raw, {
     expectedName: "payday-bot",
     expectedHandlePda: handleAccount,
-    expectedNetwork: "testnet",
+    expectedNetwork: "mainnet",
     addressRecords: liveRecords(records), // "the chain wins" cross-check
   });
   if (result.ok) {
@@ -575,7 +587,7 @@ 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";
+import { buildX402Requirements, X1_MAINNET_NETWORK } from "@x1id/resolve";
 
 // server-side: one accepts[] entry for a 402 response
 const requirements = buildX402Requirements({
@@ -583,6 +595,8 @@ const requirements = buildX402Requirements({
   asset: usdcMint,
   amount: "1000000", // smallest units, decimal string
   buyer: buyerAddress, // x1id v1 is self-sponsored: buyer pays their own fee, no facilitator
+  network: X1_MAINNET_NETWORK, // defaults to mainnet; a server on another cluster
+                               // should pass x402NetworkForGenesis(await getGenesisHash)
   memo: "invoice-42",
 });
 ```
@@ -592,6 +606,12 @@ 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.
 
+> **Buyers: wait for `finalized`.** The x1id resource server verifies the
+> payment transaction at **finalized** commitment, not `confirmed` — a buyer
+> that submits its payment and retries the request while the tx is only
+> `confirmed` gets a `402 "payment not yet confirmed; finalize it and retry"`.
+> Poll the signature to `finalized` before the retry.
+
 ## Errors
 
 `ResolveError` carries a `code` a UI can branch on:
@@ -623,7 +643,7 @@ that is a homograph vector (`@аlice` with a Cyrillic `а` renders identically t
 createResolver(config: ResolverConfig): Resolver
 
 interface ResolverConfig {
-  rpcUrl: string;            // any X1 RPC (testnet for @handles today)
+  rpcUrl: string;            // any X1 RPC (mainnet for @handles; testnet works the same)
   wasm: WasmResolver;        // required — derivation runs in WASM, no JS fallback
   fetchImpl?: typeof fetch;  // custom transport (tests, proxies)
   cacheTtlMs?: number;       // default 30_000; 0 disables (resolve() only)

package/dist/accounts.d.ts

@@ -9,10 +9,7 @@
  */
 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 DEFAULT_HANDLE_PROGRAM: string;
 export declare const TOKEN_ACCOUNT_MIN_LEN = 72;
 export declare const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
 /** The fields of a `Handle` account readers need. */
@@ -34,6 +31,16 @@ export interface ParsedHandle {
      * of) the `registeredAt` epoch rule — see docs/record-trust.md.
      */
     readonly recordsClearedAt: bigint;
+    /**
+     * `Handle.holder_epoch` (0 if absent/never bumped) — H5 / PR #466. Bumped to
+     * `now + 1` ONLY by `buy_handle`'s tokenized branch (a NATIVE pNFT ownership
+     * change); an EXTERNAL marketplace trade of the pNFT does NOT bump it. Read
+     * from the fixed raw byte offset 255 (discriminator included); an account
+     * shorter than 263 bytes reads as 0. The on-chain attestation gate requires
+     * `attested_at >= max(registered_at, holder_epoch)`, so it is a THIRD
+     * independent staleness anchor for attestations — see attestation.ts.
+     */
+    readonly holderEpoch: bigint;
     /** Set when the handle is tokenized (NFT extension present). */
     readonly nftMint: Uint8Array | null;
 }

package/dist/accounts.js

@@ -9,10 +9,20 @@
  */
 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";
+/** The @handle registry program on X1 — the TESTNET deployment, which is the
+ *  default on every surface today. Deployed with the same keypair on mainnet,
+ *  so the id is unchanged there by default; a future mainnet-only deployment
+ *  can be pointed at per-call via `handleProgramId`, or globally (for Node /
+ *  server consumers that construct the resolver without an explicit id) by
+ *  setting `X1_HANDLE_PROGRAM_ID` in the environment.
+ *
+ *  Read through `globalThis.process` (not a bare `process.env`) so this still
+ *  compiles in the @types/node-free SDK build and is simply `undefined` in the
+ *  browser — identical testnet behaviour everywhere until the env var is set at
+ *  cutover. Same pattern as `signin.ts`. */
+const TESTNET_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
+const ENV_HANDLE_PROGRAM = globalThis.process?.env?.X1_HANDLE_PROGRAM_ID;
+export const DEFAULT_HANDLE_PROGRAM = ENV_HANDLE_PROGRAM || TESTNET_HANDLE_PROGRAM;
 // 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
@@ -32,6 +42,16 @@ const HANDLE_BASE_LEN = 8 + 149;
 // leniently — a short or zeroed account means "never cleared" (0), same
 // convention as every other Handle extension region.
 const RECORDS_CLEARED_EXT_OFFSET = 229;
+// `holder_epoch` extension (`Handle::HOLDER_EPOCH_EXT_OFFSET`, H5 / PR #466):
+// an i64 LE bumped (to now+1) ONLY by `buy_handle`'s tokenized branch — a
+// NATIVE pNFT ownership change. External (off-platform, e.g. Magic Eden) pNFT
+// trades do NOT bump it. The on-chain attestation gate now requires
+// `attested_at >= max(registered_at, holder_epoch)`, so it is a THIRD staleness
+// anchor alongside `registered_at` and `records_cleared_at`. KNOWN_EXT_END
+// moved 255 -> 263 on-chain. Read leniently at the FIXED raw byte offset 255
+// (discriminator included): an account SHORTER than 263 bytes never grew this
+// region → read it as 0, the same convention as every other Handle extension.
+const HOLDER_EPOCH_EXT_OFFSET = 255;
 // 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 | ...
@@ -89,7 +109,8 @@ export function parseHandleAccount(data) {
         ? data.slice(HANDLE_BASE_LEN + 1, HANDLE_BASE_LEN + 33)
         : null;
     const recordsClearedAt = data.length >= RECORDS_CLEARED_EXT_OFFSET + 8 ? readI64(data, RECORDS_CLEARED_EXT_OFFSET) : 0n;
-    return { name, owner, registeredAt, recordsClearedAt, nftMint };
+    const holderEpoch = data.length >= HOLDER_EPOCH_EXT_OFFSET + 8 ? readI64(data, HOLDER_EPOCH_EXT_OFFSET) : 0n;
+    return { name, owner, registeredAt, recordsClearedAt, holderEpoch, nftMint };
 }
 /** Build the RPC plumbing every reader in this package shares. */
 export function makeAccountReader(rpcUrl, fetchImpl) {

package/dist/agent.js

@@ -23,7 +23,7 @@
  * WP #8133. `AgentVerificationLevel` still names level 2 so every surface
  * that reports a level shares one vocabulary.
  */
-import { X1_TESTNET_NETWORK } from "./x402.js";
+import { X1_TESTNET_NETWORK, X1_MAINNET_NETWORK } from "./x402.js";
 // ---------------------------------------------------------------------------
 // Well-known text-record keys
 // ---------------------------------------------------------------------------
@@ -188,11 +188,11 @@ export function x402AcceptsFromManifest(manifest, opts) {
     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 : "solana:mainnet-unassigned");
+    // The verified CAIP-30 x402 network ids (see x402.ts). A manifest's own
+    // explicit `x402.network` wins; otherwise map its declared cluster to the
+    // matching id — "testnet" → X1_TESTNET_NETWORK, anything else (mainnet, the
+    // production default) → X1_MAINNET_NETWORK.
+    const network = x402?.network ?? (manifest.x1id.network === "testnet" ? X1_TESTNET_NETWORK : X1_MAINNET_NETWORK);
     const payTo = opts?.payTo ?? manifest.payment?.addresses?.[0]?.address;
     return x402Endpoints.map((e) => {
         const hint = {

package/dist/attestation.d.ts

@@ -39,17 +39,22 @@
  * 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):
+ * (docs/record-trust.md, the universal rule), now anchored to the LATER of
+ * two native-ownership epochs (H5 / PR #466 added `holder_epoch`):
  *
- *     attestation.attested_at >= handle.registered_at
+ *     attestation.attested_at >= max(handle.registered_at, handle.holder_epoch)
  *
- * 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.)
+ * `holder_epoch` is bumped (to now+1) by `buy_handle`'s tokenized branch — a
+ * NATIVE pNFT sale — so a native trade now DOES move the epoch and invalidate
+ * the seller's attestation. An attestation that fails the rule 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 remaining blind spot — shared with
+ * `Handle.owner`/`Primary`/`RecordDelegate`: an EXTERNAL, off-platform
+ * bearer-NFT trade bumps no epoch, so the attestation keeps reading live
+ * until the attestor re-reviews or revokes — is what the separate
+ * `holderMismatch` overlay catches.)
  *
  * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
  *
@@ -58,7 +63,10 @@
  * 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`.
+ * EITHER `attested_at < max(registeredAt, holderEpoch)` OR
+ * `attested_at < recordsClearedAt` — where `holderEpoch` (H5 / PR #466, also
+ * from `ParsedHandle`, 0 if absent) folds the last native tokenized-buy epoch
+ * into the ownership anchor.
  */
 import type { AddressLike, BuiltInstruction } from "./delegate.js";
 import type { RpcFn } from "./accounts.js";
@@ -175,12 +183,31 @@ export interface HandleAttestation {
      *  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.
+     * The rule docs/record-trust.md mandates: this attestation only vouches for
+     * the current owner if `attested_at >= max(handle.registered_at,
+     * handle.holder_epoch)` AND `attested_at >= handle.records_cleared_at` (H5 /
+     * PR #466 added the `holder_epoch` term — the last native tokenized-buy
+     * epoch). 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;
+    /**
+     * H5 (the inherited-badge blind spot) — the OTHER, holder-level reason an
+     * attestation must not be rendered, independent of `stale`. An attestation
+     * records no subject wallet, only `attestedAt`; its epoch is anchored to
+     * `Handle.owner` (the owner stamped alongside `registered_at` at the last
+     * native ownership change). For a TOKENIZED handle, the real authority is the
+     * pNFT holder, which can diverge from `Handle.owner` with NO on-chain epoch
+     * bump (a bearer-NFT trade — native or external — writes no `registered_at`,
+     * see this struct's doc). When the current holder is no longer the mint-time
+     * `Handle.owner` the attestation was issued under, the attestation may have
+     * been inherited through a trade rather than earned, so it must NOT verify the
+     * current holder. `decodeAttestation` cannot know this (it sees no holder), so
+     * it always sets `false`; apply {@link markHolderMismatch} with the caller's
+     * holder-vs-owner comparison to set it. Mirrors tools/api's `holder_mismatch`
+     * (`build_verifications`). ALWAYS `false` for an untokenized handle.
+     */
+    readonly holderMismatch: boolean;
 }
 /**
  * Decode one Attestation account.
@@ -188,22 +215,55 @@ export interface HandleAttestation {
  * `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).
+ * SECOND independent staleness anchor. `holderEpoch` (H5 / PR #466, 0 if
+ * absent) is the THIRD: the effective ownership epoch is
+ * `max(registeredAt, holderEpoch)`, so `stale` is `attestedAt <
+ * max(registeredAt, holderEpoch) || attestedAt < recordsClearedAt` — mirroring
+ * the on-chain gate `attested_at >= max(registered_at, holder_epoch)`.
+ * `holderEpoch` defaults to `0n` for backward compatibility (a caller that has
+ * not read it degrades to the pre-H5 `>= registered_at` rule). There is
+ * intentionally no overload without `registeredAt`/`recordsClearedAt` (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
+export declare function decodeAttestation(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: bigint, holderEpoch?: bigint): HandleAttestation | null;
+/** The attestations that vouch for the CURRENT holder — `stale` ones (previous
+ *  epoch) AND `holderMismatch` ones (H5: inherited by a different pNFT holder)
  *  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).
+ * surviving `kindName`s say which signals proved it). An attestation flagged
+ * {@link HandleAttestation.holderMismatch} (H5 — the pNFT moved to a holder it
+ * was not issued to) is excluded exactly like a stale one.
  */
 export declare function isHandleVerified(attestations: readonly HandleAttestation[]): boolean;
+/**
+ * H5 — the inherited-badge overlay. Returns `attestations` with
+ * {@link HandleAttestation.holderMismatch} forced `true` on every entry when a
+ * handle is tokenized AND its pNFT has moved away from the mint-time
+ * `Handle.owner` the attestation was issued under (`holderMatchesOwner ===
+ * false`); otherwise the list is returned unchanged. An attestation records no
+ * subject wallet, so this is the one honest, off-chain-derivable signal: the
+ * current bearer is compared to `Handle.owner` (the owner stamped alongside
+ * `registered_at`), not to the holder as-of each `attestedAt`.
+ *
+ * Mirrors tools/api's `build_verifications` exactly (same `tokenized &&
+ * !holder_matches_owner` condition, same force-not-verified result). Pure and
+ * synchronous: the caller resolves the current holder (e.g. via
+ * {@link import("./accounts.js").nftHolder} / `getTokenLargestAccounts`) and
+ * compares it to the handle's `owner` ({@link
+ * import("./accounts.js").parseHandleAccount}) to produce `holderMatchesOwner`.
+ *
+ * Interim limitation (shared with the resolver): it cannot read the NFT's
+ * transfer history, only its current bearer, so a legitimate re-attestation of a
+ * new bearer is suppressed until the on-chain H5 ownership-epoch bump lands —
+ * a false suppression, never a false assertion (the honest, conservative side).
+ */
+export declare function markHolderMismatch(attestations: readonly HandleAttestation[], tokenized: boolean, holderMatchesOwner: boolean): HandleAttestation[];
 /**
  * Fetch every Attestation account of a handle — one `getProgramAccounts`
  * call, filtered by the RPC on size (114), the Attestation discriminator at
@@ -216,11 +276,15 @@ export declare function isHandleVerified(attestations: readonly HandleAttestatio
  * 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}.
+ * `holderEpoch` is that same Handle's `holderEpoch` (0 if absent, H5 / PR
+ * #466); pass it through so the effective ownership epoch is
+ * `max(registeredAt, holderEpoch)`. It defaults to `0n` for backward
+ * compatibility. 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 declare function fetchAttestations(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, holderEpoch?: bigint): Promise<HandleAttestation[]>;
 export interface SetAttestorParams {
     /** The registry program id. */
     readonly programId: AddressLike;

package/dist/attestation.js

@@ -39,17 +39,22 @@
  * 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):
+ * (docs/record-trust.md, the universal rule), now anchored to the LATER of
+ * two native-ownership epochs (H5 / PR #466 added `holder_epoch`):
  *
- *     attestation.attested_at >= handle.registered_at
+ *     attestation.attested_at >= max(handle.registered_at, handle.holder_epoch)
  *
- * 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.)
+ * `holder_epoch` is bumped (to now+1) by `buy_handle`'s tokenized branch — a
+ * NATIVE pNFT sale — so a native trade now DOES move the epoch and invalidate
+ * the seller's attestation. An attestation that fails the rule 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 remaining blind spot — shared with
+ * `Handle.owner`/`Primary`/`RecordDelegate`: an EXTERNAL, off-platform
+ * bearer-NFT trade bumps no epoch, so the attestation keeps reading live
+ * until the attestor re-reviews or revokes — is what the separate
+ * `holderMismatch` overlay catches.)
  *
  * # `records_cleared_at` (#8139) — the SECOND, independent staleness rule
  *
@@ -58,7 +63,10 @@
  * 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`.
+ * EITHER `attested_at < max(registeredAt, holderEpoch)` OR
+ * `attested_at < recordsClearedAt` — where `holderEpoch` (H5 / PR #466, also
+ * from `ParsedHandle`, 0 if absent) folds the last native tokenized-buy epoch
+ * into the ownership anchor.
  */
 import { encodeBase58 } from "./base58.js";
 import { decodeBase58_32 } from "./base58.js";
@@ -238,13 +246,20 @@ export function textRecordKeyFor(kind) {
  * `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).
+ * SECOND independent staleness anchor. `holderEpoch` (H5 / PR #466, 0 if
+ * absent) is the THIRD: the effective ownership epoch is
+ * `max(registeredAt, holderEpoch)`, so `stale` is `attestedAt <
+ * max(registeredAt, holderEpoch) || attestedAt < recordsClearedAt` — mirroring
+ * the on-chain gate `attested_at >= max(registered_at, holder_epoch)`.
+ * `holderEpoch` defaults to `0n` for backward compatibility (a caller that has
+ * not read it degrades to the pre-H5 `>= registered_at` rule). There is
+ * intentionally no overload without `registeredAt`/`recordsClearedAt` (see the
+ * module docs).
  *
  * Returns null for anything that is not an Attestation: wrong length or
  * wrong discriminator.
  */
-export function decodeAttestation(raw, account, registeredAt, recordsClearedAt) {
+export function decodeAttestation(raw, account, registeredAt, recordsClearedAt, holderEpoch = 0n) {
     if (raw.length !== ATTESTATION_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -262,6 +277,14 @@ export function decodeAttestation(raw, account, registeredAt, recordsClearedAt)
     const attestedAt = dv.getBigInt64(o, true);
     o += 8;
     const attestor = encodeBase58(raw.slice(o, o + 32));
+    // H5 / PR #466: the ownership epoch an attestation must post-date is the
+    // LATER of `registered_at` (last native register/sale) and `holder_epoch`
+    // (last native tokenized buy). Mirrors the on-chain gate exactly —
+    // `attested_at >= max(registered_at, holder_epoch)` — and staleness stays
+    // INCLUSIVE at the boundary so the dangerous failure (a false "verified")
+    // can never occur: an attestation is live only if `attested_at >=` the
+    // effective epoch. `records_cleared_at` is a second, independent anchor.
+    const ownershipEpoch = registeredAt > holderEpoch ? registeredAt : holderEpoch;
     return {
         account,
         handle,
@@ -270,21 +293,53 @@ export function decodeAttestation(raw, account, registeredAt, recordsClearedAt)
         evidenceHash,
         attestedAt,
         attestor,
-        stale: attestedAt < registeredAt || attestedAt < recordsClearedAt,
+        stale: attestedAt < ownershipEpoch || attestedAt < recordsClearedAt,
+        // The decoder sees no holder — only epoch staleness is knowable here.
+        // H5 holder-mismatch is overlaid later via markHolderMismatch.
+        holderMismatch: false,
     };
 }
-/** The attestations that vouch for the CURRENT owner — `stale` ones
+/** The attestations that vouch for the CURRENT holder — `stale` ones (previous
+ *  epoch) AND `holderMismatch` ones (H5: inherited by a different pNFT holder)
  *  excluded. This is the list to judge verification from. */
 export function liveAttestations(attestations) {
-    return attestations.filter((a) => !a.stale);
+    return attestations.filter((a) => !a.stale && !a.holderMismatch);
 }
 /**
  * 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).
+ * surviving `kindName`s say which signals proved it). An attestation flagged
+ * {@link HandleAttestation.holderMismatch} (H5 — the pNFT moved to a holder it
+ * was not issued to) is excluded exactly like a stale one.
  */
 export function isHandleVerified(attestations) {
-    return attestations.some((a) => !a.stale);
+    return attestations.some((a) => !a.stale && !a.holderMismatch);
+}
+/**
+ * H5 — the inherited-badge overlay. Returns `attestations` with
+ * {@link HandleAttestation.holderMismatch} forced `true` on every entry when a
+ * handle is tokenized AND its pNFT has moved away from the mint-time
+ * `Handle.owner` the attestation was issued under (`holderMatchesOwner ===
+ * false`); otherwise the list is returned unchanged. An attestation records no
+ * subject wallet, so this is the one honest, off-chain-derivable signal: the
+ * current bearer is compared to `Handle.owner` (the owner stamped alongside
+ * `registered_at`), not to the holder as-of each `attestedAt`.
+ *
+ * Mirrors tools/api's `build_verifications` exactly (same `tokenized &&
+ * !holder_matches_owner` condition, same force-not-verified result). Pure and
+ * synchronous: the caller resolves the current holder (e.g. via
+ * {@link import("./accounts.js").nftHolder} / `getTokenLargestAccounts`) and
+ * compares it to the handle's `owner` ({@link
+ * import("./accounts.js").parseHandleAccount}) to produce `holderMatchesOwner`.
+ *
+ * Interim limitation (shared with the resolver): it cannot read the NFT's
+ * transfer history, only its current bearer, so a legitimate re-attestation of a
+ * new bearer is suppressed until the on-chain H5 ownership-epoch bump lands —
+ * a false suppression, never a false assertion (the honest, conservative side).
+ */
+export function markHolderMismatch(attestations, tokenized, holderMatchesOwner) {
+    const mismatch = tokenized && !holderMatchesOwner;
+    return attestations.map((a) => (mismatch ? { ...a, holderMismatch: true } : a));
 }
 /**
  * Fetch every Attestation account of a handle — one `getProgramAccounts`
@@ -298,11 +353,15 @@ export function isHandleVerified(attestations) {
  * 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}.
+ * `holderEpoch` is that same Handle's `holderEpoch` (0 if absent, H5 / PR
+ * #466); pass it through so the effective ownership epoch is
+ * `max(registeredAt, holderEpoch)`. It defaults to `0n` for backward
+ * compatibility. Every attestation is returned, stale ones flagged, so an
+ * owner surface can show what a previous registration left behind; anything
+ * that renders a verified badge takes {@link isHandleVerified} /
+ * {@link liveAttestations}.
  */
-export async function fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
+export async function fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt, holderEpoch = 0n) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -321,7 +380,7 @@ export async function fetchAttestations(rpc, programId, handleAccount, registere
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const decoded = decodeAttestation(raw, a.pubkey, registeredAt, recordsClearedAt);
+        const decoded = decodeAttestation(raw, a.pubkey, registeredAt, recordsClearedAt, holderEpoch);
         // Defence in depth: the memcmp filter should guarantee the handle
         // match, but a wrong offset would silently attribute someone else's
         // attestation to this handle. A malformed account is skipped, not fatal.

package/dist/domainProof.d.ts

@@ -154,13 +154,16 @@ export interface VerifyDomainAttestationResult {
  * `registeredAt` / `recordsClearedAt` are the owning Handle's fields the caller
  * already decoded (see {@link import("./accounts.js").parseHandleAccount}); they
  * are MANDATORY here for the same reason every attestation read demands them —
- * the staleness rule (`attested_at >= registered_at`, and `>= records_cleared_at`)
- * decides whether an attestation vouches for the *current* owner at all. The
+ * the staleness rule (`attested_at >= max(registered_at, holder_epoch)`, and
+ * `>= records_cleared_at`) decides whether an attestation vouches for the
+ * *current* owner at all. `holderEpoch` (H5 / PR #466, also from the decoded
+ * Handle, 0 if absent) is the optional trailing arg that supplies that third
+ * anchor; it defaults to `0n`. The
  * two halves are evaluated independently, so a caller can see which one holds:
  * a chain-read failure does not suppress the DNS answer, and vice-versa.
  *
  * Never throws: a failed chain read degrades to `attested: false` with
  * `reason: "attestation-error"`, mirroring `signin.ts`'s best-effort summary.
  */
-export declare function verifyDomainAttestation(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, domain: string, expectedWallet: string, opts?: DomainProofOptions): Promise<VerifyDomainAttestationResult>;
+export declare function verifyDomainAttestation(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, domain: string, expectedWallet: string, opts?: DomainProofOptions, holderEpoch?: bigint): Promise<VerifyDomainAttestationResult>;
 export {};

package/dist/domainProof.js

@@ -244,21 +244,24 @@ export async function verifyDomainBinding(domain, expectedWallet, opts) {
  * `registeredAt` / `recordsClearedAt` are the owning Handle's fields the caller
  * already decoded (see {@link import("./accounts.js").parseHandleAccount}); they
  * are MANDATORY here for the same reason every attestation read demands them —
- * the staleness rule (`attested_at >= registered_at`, and `>= records_cleared_at`)
- * decides whether an attestation vouches for the *current* owner at all. The
+ * the staleness rule (`attested_at >= max(registered_at, holder_epoch)`, and
+ * `>= records_cleared_at`) decides whether an attestation vouches for the
+ * *current* owner at all. `holderEpoch` (H5 / PR #466, also from the decoded
+ * Handle, 0 if absent) is the optional trailing arg that supplies that third
+ * anchor; it defaults to `0n`. The
  * two halves are evaluated independently, so a caller can see which one holds:
  * a chain-read failure does not suppress the DNS answer, and vice-versa.
  *
  * Never throws: a failed chain read degrades to `attested: false` with
  * `reason: "attestation-error"`, mirroring `signin.ts`'s best-effort summary.
  */
-export async function verifyDomainAttestation(rpc, programId, handleAccount, registeredAt, recordsClearedAt, domain, expectedWallet, opts) {
+export async function verifyDomainAttestation(rpc, programId, handleAccount, registeredAt, recordsClearedAt, domain, expectedWallet, opts, holderEpoch = 0n) {
     // Half 1 (on-chain): a non-stale dns attestation for the current owner. A
     // read failure must not sink the DNS half — degrade, never throw.
     let attested = false;
     let attestationReason;
     try {
-        const attestations = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt);
+        const attestations = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt, holderEpoch);
         attested = attestationsPassGate(attestations, { kind: GateKind.dns });
     }
     catch {