@x1id/resolve 0.10.0 → 0.12.0

package/README.md

@@ -274,6 +274,65 @@ for (const a of liveAttestations(atts)) {
 integrator joining a live attestation to its paired text record reads the same
 mapping the program, resolver and app badge use.
 
+## Attestation gating (allowlists)
+
+Gate your app, Discord, mint, or airdrop by whether an `@handle` holds a
+**verified on-chain attestation** — any signal, or a specific platform like
+"verified GitHub." You reuse X1ID's blue-tick oracle as your allowlist instead of
+running your own verification, and the staleness rule (an attestation only counts
+for the *current* owner) is enforced for you.
+
+```ts
+import {
+  handlePassesGate, attestationsPassGate, GateKind, type Gate,
+} from "@x1id/resolve";
+
+const anyVerified: Gate = "any-verified";          // any blue-tick
+const githubOnly: Gate  = { kind: GateKind.github }; // one platform
+const xOrGithub: Gate   = { anyOf: [GateKind.x, GateKind.github] };
+
+// One-call fetch + check (handleAccount/registeredAt/recordsClearedAt come from
+// the handle you resolved):
+const { passed, attestations } = await handlePassesGate(
+  rpc, programId, handleAccount, registeredAt, recordsClearedAt, githubOnly,
+);
+if (!passed) throw new Error("Not allowed — verify your GitHub on X1ID first.");
+
+// Already have the attestations? The check is pure + synchronous:
+attestationsPassGate(attestations, xOrGithub); // boolean
+```
+
+`GateKind`: `dns`, `social`, `x`, `discord`, `github`, `telegram`.
+
+**On-chain gate (CPI):** another program can verify the same thing inside its own
+transaction via the program-native `assert_attestation_gate` instruction — it
+returns Ok when the gate passes and errors otherwise, so a CPI that errors fails
+the caller's tx. Full call contract (discriminator, accounts, kind codes) is in
+the program's `docs/attestation-gating.md`.
+
+**Hosted gate + drop-in middleware (X1ID Gate):** if you'd rather not run your own
+attestation reads, `requireGate()` calls the hosted decision service
+(`POST /v1/gate/check`, api.x1id.io) and returns pass/fail. A tiny, framework-
+agnostic **server** guard (keep your API key server-side):
+
+```ts
+import { requireGate, GateKind } from "@x1id/resolve";
+
+const gate = requireGate({ apiKey: process.env.X1ID_API_KEY! }, { kind: GateKind.github });
+
+export async function POST(req: Request) {           // any server runtime with fetch
+  const { handle } = await req.json();
+  const { allowed } = await gate({ handle });        // or gate({ wallet })
+  if (!allowed) return Response.json({ error: "verified GitHub required" }, { status: 403 });
+  // …proceed
+}
+```
+
+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.
+
 ## What works today
 
 | | Status |
@@ -284,17 +343,19 @@ mapping the program, resolver and app badge use.
 | Per-chain ETH/BTC records | ✅ read with the staleness rule enforced structurally |
 | Control proofs (prove you control a `@handle`) | ✅ `createControlChallenge` / `verifyControlProof` — spec: `docs/control-proof.md` |
 | Records read (per-chain, staleness-enforced) | ✅ `fetchRecords` |
-| Subnames · gifts · integrator rev-share · name-lock · record-delegate · text records · attestations (write) | ✅ 0.3.0 — instruction builders; you sign & relay |
-| Registration / transfer / `set_primary` (write) | 🔜 roadmap — use [x1id.io](https://x1id.io) |
+| Attestation gating (verified-only allowlists) | ✅ off-chain (`handlePassesGate`) + on-chain CPI (`assert_attestation_gate`) |
+| Registration · lease-to-own · FORTI · commit-reveal · gift-voucher claim (write) | ✅ instruction builders; you sign & relay |
+| Subnames · gifts · integrator rev-share · name-lock · record-delegate · text records · attestations (write) | ✅ instruction builders; you sign & relay |
+| `transfer` / `set_primary` (write) | 🔜 roadmap — use [x1id.io](https://x1id.io) |
 
 The `@handle` registry program id is configurable (`handleProgramId`) and
 defaults to the canonical X1 deployment
 (`8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P`).
 
-## Beyond resolve: the registry write surface (0.3.0)
+## Beyond resolve: the registry write surface
 
 `resolve()` / `reverse()` / `fetchRecords()` are read-only and need only an RPC.
-0.3.0 also ships **instruction builders** for the on-chain registry. Each
+The package also ships **instruction builders** for the on-chain registry. Each
 returns an unsigned `BuiltInstruction` (`{ programId, keys, data }`) — you
 assemble it into a transaction, **sign, and relay** yourself; the SDK never
 holds keys. Every discriminator and account order matches the deployed program.
@@ -328,7 +389,10 @@ const ix = buildCreateSubnameIx({
 ```
 
 **Register a handle** (pays whatever the on-chain ramp charges as of the
-landing slot — there is no client-supplied price):
+landing slot — there is no client-supplied price). `buildRegisterIx` builds the
+plain **name-only** `register`; the default **NFT-included** purchase
+(`register_tokenized`, which mints the capability pNFT in the same transaction)
+is driven by app.x1id.io today and has no standalone SDK builder yet:
 
 ```ts
 import { buildRegisterIx, fetchConfigTreasury, HandleType } from "@x1id/resolve";
@@ -369,6 +433,11 @@ Also shipped, same build → sign → relay shape:
 | Record-write delegation | `buildSetRecordDelegateIx`, `buildRevokeRecordDelegateIx` |
 | Typed text records (website / avatar / socials) | `buildCreateTextRecordIx`, `buildUpdateTextRecordIx`, `buildCloseTextRecordIx` |
 | Register a handle | `buildRegisterIx` (+ `fetchConfigTreasury`) |
+| Lease-to-own | `buildRegisterLeasedIx`, `buildRenewLeaseIx`, `buildReclaimExpiredLeaseIx` |
+| Register at a FORTI discount | `buildRegisterWithFortiIx` |
+| Commit-reveal registration (front-run-safe) | `buildCommitIx`, `buildRegisterRevealedIx`, `buildCancelCommitmentIx` |
+| Claim a gifted name (prepaid voucher) | `buildClaimVoucherIx`, `buildClaimVoucherTokenizedIx` |
+| Attestation gating | `handlePassesGate`, `attestationsPassGate`, `GateKind` — see [Attestation gating](#attestation-gating-allowlists) |
 | 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 / per-platform attestations | `buildCreateAttestationIx` (kinds 0–5), `buildCloseAttestationIx` (+ `fetchAttestations`, `isHandleVerified`, `platformSlug`, `textRecordKeyFor`) — see [Per-platform verification](#per-platform-verification-verified-by-platform) |
 | Agent records (identity, manifest, x402 hints) | `validateManifest`, `agentVerificationLevel`, `x402AcceptsFromManifest`, `agentTextRecords` — see [Agent records](#agent-records) below |

package/dist/adminConfig.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Admin-only `Config` setters — `set_tiers` / `set_nft_tiers` (#8398) and (as
+ * the on-chain admin batch lands) the rest of the AdminOnly config instructions.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. All of these share the `AdminOnly` account shape:
+ *   admin  (signer, NOT writable — these setters init nothing, so no rent)
+ *   config (the ["config"] PDA, writable)
+ * and must be signed by `Config.admin`. PDAs are not derived here — derive
+ * `["config"]` with your runtime's `findProgramAddress`.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** Anchor instruction discriminator: `sha256("global:set_tiers")[0..8]`. */
+export declare const SET_TIERS_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:set_nft_tiers")[0..8]`. */
+export declare const SET_NFT_TIERS_DISCRIMINATOR: Uint8Array;
+/** The number of length-tiers in `Config.tier_lamports` / `nft_tier_lamports`.
+ *  Tier index = `clamp(nameLen, 1, 10) - 1`, so tier[0] = 1-char … tier[9] = 10+. */
+export declare const TIER_COUNT = 10;
+export interface SetTiersParams {
+    readonly programId: AddressLike;
+    /** `Config.admin` — the ONLY key accepted (has_one = admin). Signs; not mut. */
+    readonly admin: AddressLike;
+    /** The `["config"]` PDA (writable). */
+    readonly config: AddressLike;
+    /** Exactly 10 per-length-tier base prices in lamports (tier[0]=1-char …
+     *  tier[9]=10+). Accepts number or bigint; each must be a non-negative
+     *  integer that fits u64. */
+    readonly tierLamports: ReadonlyArray<number | bigint>;
+}
+/** Build `set_tiers` — replace the 10 length-tier base registration prices. */
+export declare function buildSetTiersIx(p: SetTiersParams): BuiltInstruction;
+export interface SetNftTiersParams {
+    readonly programId: AddressLike;
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    /** Exactly 10 per-length-tier NFT mint fees in lamports. */
+    readonly nftTierLamports: ReadonlyArray<number | bigint>;
+}
+/** Build `set_nft_tiers` — replace the 10 length-tier `mint_handle_nft` fees. */
+export declare function buildSetNftTiersIx(p: SetNftTiersParams): BuiltInstruction;
+export declare const SET_LEASE_RATE_DIVISOR_DISCRIMINATOR: Uint8Array;
+export declare const SET_LEASE_GRACE_PERIOD_DISCRIMINATOR: Uint8Array;
+export declare const SET_RECOVERY_TIMELOCK_DISCRIMINATOR: Uint8Array;
+export declare const SET_MIN_COMMITMENT_AGE_DISCRIMINATOR: Uint8Array;
+export declare const SET_MAX_COMMITMENT_AGE_DISCRIMINATOR: Uint8Array;
+/** Map an admin config action name → its discriminator (for a relay executor
+ *  that dispatches on the action string). set_admin/set_attestor intentionally
+ *  absent — those are owner-gated, never dispatched here. */
+export declare const ADMIN_SCALAR_DISCRIMINATORS: Readonly<Record<string, Uint8Array>>;
+export interface AdminScalarParams {
+    readonly programId: AddressLike;
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    /** The discriminator for the specific setter (from ADMIN_SCALAR_DISCRIMINATORS). */
+    readonly discriminator: Uint8Array;
+    /** The integer arg (u64/i64 encoding is identical for a non-negative value). */
+    readonly value: number | bigint;
+}
+/** Build any one-integer-arg AdminOnly setter (lease rate divisor, lease grace,
+ *  recovery timelock, min/max commitment age). disc(8) + value as little-endian
+ *  u64(8). The value must be a non-negative integer that fits u64. */
+export declare function buildAdminScalarSetterIx(p: AdminScalarParams): BuiltInstruction;

package/dist/adminConfig.js

@@ -0,0 +1,113 @@
+/**
+ * Admin-only `Config` setters — `set_tiers` / `set_nft_tiers` (#8398) and (as
+ * the on-chain admin batch lands) the rest of the AdminOnly config instructions.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. All of these share the `AdminOnly` account shape:
+ *   admin  (signer, NOT writable — these setters init nothing, so no rent)
+ *   config (the ["config"] PDA, writable)
+ * and must be signed by `Config.admin`. PDAs are not derived here — derive
+ * `["config"]` with your runtime's `findProgramAddress`.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+/** Anchor instruction discriminator: `sha256("global:set_tiers")[0..8]`. */
+export const SET_TIERS_DISCRIMINATOR = Uint8Array.from([
+    170, 131, 109, 175, 156, 214, 177, 121,
+]);
+/** Anchor instruction discriminator: `sha256("global:set_nft_tiers")[0..8]`. */
+export const SET_NFT_TIERS_DISCRIMINATOR = Uint8Array.from([
+    116, 68, 126, 146, 252, 206, 87, 61,
+]);
+/** The number of length-tiers in `Config.tier_lamports` / `nft_tier_lamports`.
+ *  Tier index = `clamp(nameLen, 1, 10) - 1`, so tier[0] = 1-char … tier[9] = 10+. */
+export const TIER_COUNT = 10;
+function encodeTiers(disc, tiers) {
+    if (tiers.length !== TIER_COUNT) {
+        throw new Error(`expected exactly ${TIER_COUNT} tiers, got ${tiers.length}`);
+    }
+    // Fixed-size [u64; 10] — borsh writes 10 little-endian u64s back to back, NO
+    // length prefix (unlike a Vec or a String).
+    const data = new Uint8Array(8 + TIER_COUNT * 8);
+    data.set(disc, 0);
+    const dv = new DataView(data.buffer);
+    for (let i = 0; i < TIER_COUNT; i++) {
+        const raw = tiers[i]; // length checked above
+        const v = typeof raw === "bigint" ? raw : BigInt(raw);
+        if (v < 0n || v > 0xffffffffffffffffn) {
+            throw new Error(`tier[${i}] = ${raw} is out of u64 range`);
+        }
+        dv.setBigUint64(8 + i * 8, v, true);
+    }
+    return data;
+}
+function adminOnlyKeys(admin, config) {
+    return [
+        // admin signs but is NOT writable — these setters init nothing (no rent).
+        { pubkey: toBase58(admin, "admin"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(config, "config"), isSigner: false, isWritable: true },
+    ];
+}
+/** Build `set_tiers` — replace the 10 length-tier base registration prices. */
+export function buildSetTiersIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: adminOnlyKeys(p.admin, p.config),
+        data: encodeTiers(SET_TIERS_DISCRIMINATOR, p.tierLamports),
+    };
+}
+/** Build `set_nft_tiers` — replace the 10 length-tier `mint_handle_nft` fees. */
+export function buildSetNftTiersIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: adminOnlyKeys(p.admin, p.config),
+        data: encodeTiers(SET_NFT_TIERS_DISCRIMINATOR, p.nftTierLamports),
+    };
+}
+// ===== Scalar AdminOnly setters (#8399/recovery/commitment) =====
+// Each takes one little-endian integer arg. Same AdminOnly account shape.
+export const SET_LEASE_RATE_DIVISOR_DISCRIMINATOR = Uint8Array.from([181, 218, 76, 213, 80, 99, 181, 52]);
+export const SET_LEASE_GRACE_PERIOD_DISCRIMINATOR = Uint8Array.from([212, 2, 110, 20, 130, 50, 194, 186]);
+export const SET_RECOVERY_TIMELOCK_DISCRIMINATOR = Uint8Array.from([178, 183, 148, 243, 155, 166, 79, 6]);
+export const SET_MIN_COMMITMENT_AGE_DISCRIMINATOR = Uint8Array.from([181, 20, 114, 43, 51, 23, 47, 248]);
+export const SET_MAX_COMMITMENT_AGE_DISCRIMINATOR = Uint8Array.from([163, 106, 196, 206, 146, 156, 79, 249]);
+/** Map an admin config action name → its discriminator (for a relay executor
+ *  that dispatches on the action string). set_admin/set_attestor intentionally
+ *  absent — those are owner-gated, never dispatched here. */
+export const ADMIN_SCALAR_DISCRIMINATORS = {
+    set_lease_rate_divisor: SET_LEASE_RATE_DIVISOR_DISCRIMINATOR,
+    set_lease_grace_period: SET_LEASE_GRACE_PERIOD_DISCRIMINATOR,
+    set_recovery_timelock: SET_RECOVERY_TIMELOCK_DISCRIMINATOR,
+    set_min_commitment_age: SET_MIN_COMMITMENT_AGE_DISCRIMINATOR,
+    set_max_commitment_age: SET_MAX_COMMITMENT_AGE_DISCRIMINATOR,
+};
+/** Build any one-integer-arg AdminOnly setter (lease rate divisor, lease grace,
+ *  recovery timelock, min/max commitment age). disc(8) + value as little-endian
+ *  u64(8). The value must be a non-negative integer that fits u64. */
+export function buildAdminScalarSetterIx(p) {
+    const raw = typeof p.value === "bigint" ? p.value : BigInt(p.value);
+    if (raw < 0n || raw > 0xffffffffffffffffn) {
+        throw new Error(`value ${p.value} is out of u64 range`);
+    }
+    const data = new Uint8Array(8 + 8);
+    data.set(p.discriminator, 0);
+    new DataView(data.buffer).setBigUint64(8, raw, true);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: adminOnlyKeys(p.admin, p.config),
+        data,
+    };
+}

package/dist/adminMarket.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Admin-only marketplace config (`set_market_config`, #8401) and the namespace
+ * directory setters (`create_namespace` / `set_namespace_status`, #8403). The
+ * integrator setters (add/set_rate/remove) already live in ./integrator.ts and
+ * are reused, not duplicated here.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. Unlike the AdminOnly setters in adminConfig.ts, these do
+ * NOT share one account shape: `config` is read-only here (it's the has_one =
+ * admin authority check), and the written account differs per instruction
+ * (`market_config` or a `Namespace`). PDAs are not derived here — derive
+ * `["market_config"]`, `["namespace", label]`, `["config"]` with your runtime's
+ * findProgramAddress and pass them in, same convention as adminConfig.ts.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** The System Program — required by the two `init` instructions (add_integrator,
+ *  create_namespace). A fixed well-known address, hardcoded so callers can't
+ *  mistype it. */
+export declare const SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
+/** Anchor discriminator sha256("global:set_market_config")[0..8]. */
+export declare const SET_MARKET_CONFIG_DISCRIMINATOR: Uint8Array;
+export interface SetMarketConfigParams {
+    readonly programId: AddressLike;
+    /** `Config.admin` — signs; NOT writable. */
+    readonly admin: AddressLike;
+    /** `["config"]` PDA — read-only (the has_one authority check). */
+    readonly config: AddressLike;
+    /** `["market_config"]` PDA — writable. */
+    readonly marketConfig: AddressLike;
+    readonly feeBps: number;
+    readonly minBidIncrementBps: number;
+    readonly antiSnipeWindow: number;
+    readonly antiSnipeExtend: number;
+    readonly minAuctionSecs: number;
+    readonly maxAuctionSecs: number;
+    readonly paused: boolean;
+}
+/** Build `set_market_config` — fee/auction params + the global pause flag.
+ *  Enforces the same bounds the program's validate_market_params does. */
+export declare function buildSetMarketConfigIx(p: SetMarketConfigParams): BuiltInstruction;
+export declare const CREATE_NAMESPACE_DISCRIMINATOR: Uint8Array;
+export declare const SET_NAMESPACE_STATUS_DISCRIMINATOR: Uint8Array;
+export declare const NAMESPACE_MAX_LEN = 16;
+export type NamespaceStatus = "Active" | "Paused" | "Retired";
+export interface CreateNamespaceParams {
+    readonly programId: AddressLike;
+    /** admin — signs AND pays rent; writable. */
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    /** `["namespace", label]` PDA — init, writable. */
+    readonly namespace: AddressLike;
+    /** Canonical ASCII label (a-z 0-9 -), 1..=16 bytes — an instruction ARG. */
+    readonly label: string;
+    readonly systemProgram?: AddressLike;
+}
+/** Build `create_namespace` — label is a borsh String arg. */
+export declare function buildCreateNamespaceIx(p: CreateNamespaceParams): BuiltInstruction;
+export interface SetNamespaceStatusParams {
+    readonly programId: AddressLike;
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    /** `["namespace", label]` PDA — writable. */
+    readonly namespace: AddressLike;
+    readonly status: NamespaceStatus;
+}
+/** Build `set_namespace_status` — status enum as a single-byte discriminant. */
+export declare function buildSetNamespaceStatusIx(p: SetNamespaceStatusParams): BuiltInstruction;

package/dist/adminMarket.js

@@ -0,0 +1,134 @@
+/**
+ * Admin-only marketplace config (`set_market_config`, #8401) and the namespace
+ * directory setters (`create_namespace` / `set_namespace_status`, #8403). The
+ * integrator setters (add/set_rate/remove) already live in ./integrator.ts and
+ * are reused, not duplicated here.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. Unlike the AdminOnly setters in adminConfig.ts, these do
+ * NOT share one account shape: `config` is read-only here (it's the has_one =
+ * admin authority check), and the written account differs per instruction
+ * (`market_config` or a `Namespace`). PDAs are not derived here — derive
+ * `["market_config"]`, `["namespace", label]`, `["config"]` with your runtime's
+ * findProgramAddress and pass them in, same convention as adminConfig.ts.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** The System Program — required by the two `init` instructions (add_integrator,
+ *  create_namespace). A fixed well-known address, hardcoded so callers can't
+ *  mistype it. */
+export const SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+// ---- borsh scalar writers -------------------------------------------------
+function u16le(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 0xffff)
+        throw new Error(`u16 out of range: ${n}`);
+    const b = new Uint8Array(2);
+    new DataView(b.buffer).setUint16(0, n, true);
+    return b;
+}
+function u32le(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 0xffff_ffff)
+        throw new Error(`u32 out of range: ${n}`);
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, true);
+    return b;
+}
+function concat(parts) {
+    const len = parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(len);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+// ===== #8401 set_market_config =====
+/** Anchor discriminator sha256("global:set_market_config")[0..8]. */
+export const SET_MARKET_CONFIG_DISCRIMINATOR = Uint8Array.from([128, 237, 216, 59, 122, 62, 156, 30]);
+/** Build `set_market_config` — fee/auction params + the global pause flag.
+ *  Enforces the same bounds the program's validate_market_params does. */
+export function buildSetMarketConfigIx(p) {
+    if (p.feeBps > 10_000)
+        throw new Error("feeBps must be <= 10000");
+    if (p.minBidIncrementBps > 10_000)
+        throw new Error("minBidIncrementBps must be <= 10000");
+    if (p.minAuctionSecs <= 0)
+        throw new Error("minAuctionSecs must be > 0");
+    if (p.maxAuctionSecs < p.minAuctionSecs)
+        throw new Error("maxAuctionSecs must be >= minAuctionSecs");
+    if (p.antiSnipeExtend < p.antiSnipeWindow)
+        throw new Error("antiSnipeExtend must be >= antiSnipeWindow");
+    const data = concat([
+        SET_MARKET_CONFIG_DISCRIMINATOR,
+        u16le(p.feeBps),
+        u16le(p.minBidIncrementBps),
+        u32le(p.antiSnipeWindow),
+        u32le(p.antiSnipeExtend),
+        u32le(p.minAuctionSecs),
+        u32le(p.maxAuctionSecs),
+        Uint8Array.from([p.paused ? 1 : 0]),
+    ]);
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.marketConfig, "marketConfig"), isSigner: false, isWritable: true },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+// NOTE: the integrator builders (add_integrator / set_integrator_rate /
+// remove_integrator) + decodeAllowlistEntry already live in ./integrator.ts —
+// reuse those, they are not duplicated here.
+// ===== #8403 namespaces =====
+export const CREATE_NAMESPACE_DISCRIMINATOR = Uint8Array.from([205, 189, 35, 255, 214, 116, 25, 107]);
+export const SET_NAMESPACE_STATUS_DISCRIMINATOR = Uint8Array.from([41, 135, 103, 92, 151, 13, 61, 158]);
+export const NAMESPACE_MAX_LEN = 16;
+const NAMESPACE_STATUS_DISCRIMINANT = {
+    Active: 0,
+    Paused: 1,
+    Retired: 2,
+};
+function borshString(s) {
+    const bytes = new TextEncoder().encode(s);
+    return concat([u32le(bytes.length), bytes]);
+}
+/** Build `create_namespace` — label is a borsh String arg. */
+export function buildCreateNamespaceIx(p) {
+    if (p.label.length < 1 || p.label.length > NAMESPACE_MAX_LEN) {
+        throw new Error(`label must be 1..=${NAMESPACE_MAX_LEN} chars`);
+    }
+    const data = concat([CREATE_NAMESPACE_DISCRIMINATOR, borshString(p.label)]);
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.namespace, "namespace"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.systemProgram ?? SYSTEM_PROGRAM_ID, "systemProgram"), isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `set_namespace_status` — status enum as a single-byte discriminant. */
+export function buildSetNamespaceStatusIx(p) {
+    const disc = NAMESPACE_STATUS_DISCRIMINANT[p.status];
+    if (disc === undefined)
+        throw new Error(`unknown namespace status: ${p.status}`);
+    const data = concat([SET_NAMESPACE_STATUS_DISCRIMINATOR, Uint8Array.from([disc])]);
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.namespace, "namespace"), isSigner: false, isWritable: true },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/attestation.d.ts

@@ -91,6 +91,14 @@ export declare const ATTESTATION_KIND_TELEGRAM = 5;
  *  `>=` this on-chain; the SDK's builder enforces the same bound. Mirrors
  *  `Attestation::KIND_COUNT` (programs/x1-handles/src/state.rs). */
 export declare const ATTESTATION_KIND_COUNT = 6;
+/** `Attestation.kind` — validator control proven TRUSTLESSLY on-chain (#8486):
+ *  the vote account's `authorized_withdrawer` co-signed `attest_validator`, or
+ *  signed the challenge that `attest_validator_signed` verifies via the Ed25519
+ *  precompile. Value 6 — equal to {@link ATTESTATION_KIND_COUNT}, i.e. OUTSIDE
+ *  the attestor-mintable range (`create_attestation` refuses `>= KIND_COUNT`),
+ *  so only the cryptographic validator path can mint it. `evidenceHash` holds
+ *  the vote account pubkey; surfaced as a gold shield, not the blue tick. */
+export declare const ATTESTATION_KIND_VALIDATOR = 6;
 /** 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
@@ -104,6 +112,18 @@ export declare const SET_ATTESTOR_DISCRIMINATOR: Uint8Array;
 export declare const CREATE_ATTESTATION_DISCRIMINATOR: Uint8Array;
 /** Anchor instruction discriminator: `sha256("global:close_attestation")[0..8]`. */
 export declare const CLOSE_ATTESTATION_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:attest_validator")[0..8]` — the co-sign path. */
+export declare const ATTEST_VALIDATOR_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:attest_validator_signed")[0..8]` — the detached path. */
+export declare const ATTEST_VALIDATOR_SIGNED_DISCRIMINATOR: Uint8Array;
+/** The SVM Ed25519 signature-verification precompile — carries the withdraw
+ *  authority's detached signature for `attest_validator_signed`. */
+export declare const ED25519_PROGRAM_ID = "Ed25519SigVerify111111111111111111111111111";
+/** The Instructions sysvar — `attest_validator_signed` introspects it. */
+export declare const SYSVAR_INSTRUCTIONS_ID = "Sysvar1nstructions1111111111111111111111111";
+/** Domain-separator prefix of the validator-attestation challenge. MUST byte-
+ *  match `VALIDATOR_ATTEST_CHALLENGE_PREFIX` in programs/x1-handles/src/lib.rs. */
+export declare const VALIDATOR_ATTEST_CHALLENGE_PREFIX: 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)
@@ -112,7 +132,7 @@ export declare const ATTESTATION_LEN = 114;
 /** `AttestorConfig` account size: disc(8) + attestor(32) + bump(1). */
 export declare const ATTESTOR_CONFIG_LEN = 41;
 /** Human name an attestation `kind` byte carries. */
-export type AttestationKindName = "dns" | "social" | "x" | "discord" | "github" | "telegram";
+export type AttestationKindName = "dns" | "social" | "x" | "discord" | "github" | "telegram" | "validator";
 /** Which verification signal an attestation `kind` byte names, or null for a
  *  kind this SDK does not know (future program versions may add kinds). For the
  *  per-platform kinds this returns the platform slug; the two legacy kinds keep
@@ -272,6 +292,88 @@ export interface CloseAttestationParams {
  * a rotated-away key's output).
  */
 export declare function buildCloseAttestationIx(p: CloseAttestationParams): BuiltInstruction;
+export interface AttestValidatorParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's authority (owner, or NFT holder if tokenized); signs + pays rent. */
+    readonly owner: AddressLike;
+    /** The vote account's withdraw authority; co-signs (MAY equal `owner`). */
+    readonly withdrawAuthority: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** The validator's vote account (owned by the Vote program on-chain). */
+    readonly voteAccount: AddressLike;
+    /** The `["attestation", handle, [KIND_VALIDATOR]]` PDA. */
+    readonly attestation: AddressLike;
+    /** ONLY for a tokenized handle: the caller's associated token account for the
+     *  handle's NFT mint (the holder-proof `require_current_authority` reads). */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `attest_validator` (co-sign path). Two signers — `owner` (authorizes
+ * the link) and `withdrawAuthority` (the proof) — which MAY be the same key. No
+ * instruction args: the co-signature IS the proof.
+ */
+export declare function buildAttestValidatorIx(p: AttestValidatorParams): BuiltInstruction;
+/**
+ * The exact 96-byte challenge the withdraw authority signs for the DETACHED
+ * path: `PREFIX(24) ‖ handle(32) ‖ voteAccount(32) ‖ registeredAt i64 LE(8)`.
+ * MUST byte-match the program. `registeredAt` is the handle's on-chain
+ * `registered_at` (seconds) — pass the exact value from the Handle account.
+ */
+export declare function validatorAttestChallenge(handle: AddressLike, voteAccount: AddressLike, registeredAt: bigint | number): Uint8Array;
+export interface Ed25519VerifyParams {
+    /** The 32-byte ed25519 public key (the withdraw authority). */
+    readonly publicKey: AddressLike;
+    /** The signed message (the validator challenge). */
+    readonly message: Uint8Array;
+    /** The 64-byte ed25519 signature over `message` by `publicKey`. */
+    readonly signature: Uint8Array;
+}
+/**
+ * Build the Ed25519 precompile instruction (no accounts) proving `signature` is
+ * `publicKey`'s over `message`. SELF-CONTAINED single signature — all three
+ * instruction-index fields are `0xFFFF` — matching the exact layout
+ * `attest_validator_signed` requires. Place it IMMEDIATELY BEFORE the attest ix
+ * (use {@link buildAttestValidatorSignedIxs}).
+ */
+export declare function buildEd25519VerifyIx(p: Ed25519VerifyParams): BuiltInstruction;
+export interface AttestValidatorSignedParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's authority (owner / NFT holder); the SOLE tx signer, pays rent. */
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    readonly voteAccount: AddressLike;
+    /** The `["attestation", handle, [KIND_VALIDATOR]]` PDA. */
+    readonly attestation: AddressLike;
+    /** ONLY for a tokenized handle: the caller's ATA for the handle's NFT mint. */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build the `attest_validator_signed` ix ALONE. The withdraw authority's proof
+ * is NOT here — it rides in the Ed25519 precompile ix that MUST immediately
+ * precede this one. Prefer {@link buildAttestValidatorSignedIxs}, which returns
+ * both, in order. No instruction args.
+ */
+export declare function buildAttestValidatorSignedIx(p: AttestValidatorSignedParams): BuiltInstruction;
+export interface AttestValidatorSignedTxParams extends AttestValidatorSignedParams {
+    /** The vote account's `authorized_withdrawer` (32-byte ed25519 pubkey) whose
+     *  offline signature over the challenge this carries. */
+    readonly withdrawAuthority: AddressLike;
+    /** The 64-byte ed25519 signature over {@link validatorAttestChallenge},
+     *  produced offline by the withdraw authority. */
+    readonly signature: Uint8Array;
+    /** The handle's on-chain `registered_at` (seconds). */
+    readonly registeredAt: bigint | number;
+}
+/**
+ * Build BOTH instructions for the detached path, IN ORDER:
+ * `[ed25519VerifyIx, attestValidatorSignedIx]`. Submit them as ONE transaction
+ * in this order — the program loads the ed25519 ix at `current_index - 1`.
+ * `owner` is the only signer.
+ */
+export declare function buildAttestValidatorSignedIxs(p: AttestValidatorSignedTxParams): BuiltInstruction[];
 /** The minimal shape the verification helpers read — any {@link Resolved}
  *  satisfies it, as does a bare `{ verifications }` an integrator assembles
  *  from a raw REST payload. */