@x1id/resolve 0.15.0 → 0.16.0

package/dist/gate.d.ts

@@ -7,8 +7,12 @@
  * The gate operates on the attestations {@link fetchAttestations} returns; the
  * staleness rule (an attestation only counts for the CURRENT owner —
  * `attested_at >= handle.registered_at`) is already baked into `HandleAttestation.stale`,
- * and this module always ignores stale ones. Nothing here trusts an off-chain
- * claim: every input is an on-chain, attestor-signed `Attestation` account.
+ * and this module always ignores stale ones. It likewise ignores any attestation
+ * flagged `HandleAttestation.holderMismatch` (H5 — a tokenized handle whose pNFT
+ * moved to a holder it was not issued to), so a gate caller that overlays
+ * {@link markHolderMismatch} onto the fetched set never admits an inherited
+ * badge. Nothing here trusts an off-chain claim: every input is an on-chain,
+ * attestor-signed `Attestation` account.
  */
 import { type HandleAttestation } from "./attestation.js";
 import type { RpcFn } from "./accounts.js";
@@ -31,13 +35,16 @@ export declare const GateKind: {
     readonly telegram: 5;
 };
 /** Pure check: do these (already-fetched) attestations satisfy the gate?
- *  Stale attestations never count. */
+ *  Stale and holder-mismatched (H5) attestations never count. */
 export declare function attestationsPassGate(attestations: readonly HandleAttestation[], gate: Gate): boolean;
 /** Fetch a handle's attestations and test the gate in one call. `handleAccount`,
- *  `registeredAt` and `recordsClearedAt` come from the handle you resolved
- *  (name → `deriveHandleAccount` → decode). Returns the pass/fail plus the
+ *  `registeredAt`, `recordsClearedAt` and `holderEpoch` come from the handle you
+ *  resolved (name → `deriveHandleAccount` → decode). `holderEpoch` (H5 / PR
+ *  #466, 0 if absent) folds into the staleness epoch so the gate matches the
+ *  on-chain rule `attested_at >= max(registered_at, holder_epoch)`; it defaults
+ *  to `0n` for backward compatibility. Returns the pass/fail plus the
  *  attestations so a caller can also render WHICH signals matched. */
-export declare function handlePassesGate(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, gate: Gate): Promise<{
+export declare function handlePassesGate(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, gate: Gate, holderEpoch?: bigint): Promise<{
     readonly passed: boolean;
     readonly attestations: HandleAttestation[];
 }>;

package/dist/gate.js

@@ -7,8 +7,12 @@
  * The gate operates on the attestations {@link fetchAttestations} returns; the
  * staleness rule (an attestation only counts for the CURRENT owner —
  * `attested_at >= handle.registered_at`) is already baked into `HandleAttestation.stale`,
- * and this module always ignores stale ones. Nothing here trusts an off-chain
- * claim: every input is an on-chain, attestor-signed `Attestation` account.
+ * and this module always ignores stale ones. It likewise ignores any attestation
+ * flagged `HandleAttestation.holderMismatch` (H5 — a tokenized handle whose pNFT
+ * moved to a holder it was not issued to), so a gate caller that overlays
+ * {@link markHolderMismatch} onto the fetched set never admits an inherited
+ * badge. Nothing here trusts an off-chain claim: every input is an on-chain,
+ * attestor-signed `Attestation` account.
  */
 import { fetchAttestations, isHandleVerified, ATTESTATION_KIND_DNS, ATTESTATION_KIND_SOCIAL, ATTESTATION_KIND_X, ATTESTATION_KIND_DISCORD, ATTESTATION_KIND_GITHUB, ATTESTATION_KIND_TELEGRAM, } from "./attestation.js";
 /** Named platform kinds, re-exported so callers gate without magic numbers. */
@@ -21,18 +25,21 @@ export const GateKind = {
     telegram: ATTESTATION_KIND_TELEGRAM,
 };
 /** Pure check: do these (already-fetched) attestations satisfy the gate?
- *  Stale attestations never count. */
+ *  Stale and holder-mismatched (H5) attestations never count. */
 export function attestationsPassGate(attestations, gate) {
     if (gate === "any-verified")
         return isHandleVerified(attestations);
     const kinds = "kind" in gate ? [gate.kind] : gate.anyOf;
-    return attestations.some((a) => !a.stale && kinds.includes(a.kind));
+    return attestations.some((a) => !a.stale && !a.holderMismatch && kinds.includes(a.kind));
 }
 /** Fetch a handle's attestations and test the gate in one call. `handleAccount`,
- *  `registeredAt` and `recordsClearedAt` come from the handle you resolved
- *  (name → `deriveHandleAccount` → decode). Returns the pass/fail plus the
+ *  `registeredAt`, `recordsClearedAt` and `holderEpoch` come from the handle you
+ *  resolved (name → `deriveHandleAccount` → decode). `holderEpoch` (H5 / PR
+ *  #466, 0 if absent) folds into the staleness epoch so the gate matches the
+ *  on-chain rule `attested_at >= max(registered_at, holder_epoch)`; it defaults
+ *  to `0n` for backward compatibility. Returns the pass/fail plus the
  *  attestations so a caller can also render WHICH signals matched. */
-export async function handlePassesGate(rpc, programId, handleAccount, registeredAt, recordsClearedAt, gate) {
-    const attestations = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt);
+export async function handlePassesGate(rpc, programId, handleAccount, registeredAt, recordsClearedAt, gate, holderEpoch = 0n) {
+    const attestations = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt, holderEpoch);
     return { passed: attestationsPassGate(attestations, gate), attestations };
 }

package/dist/gateClient.d.ts

@@ -80,14 +80,16 @@ export interface GuardResult {
  * silently admitting an unverified caller. `onError: "deny"` instead resolves to
  * a clean `allowed: false` (fail-closed without a throw).
  *
- * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN. On ANY error (network blip,
- * timeout, 5xx, auth failure, a malformed response) it fabricates a
- * `passed: true` decision and admits the caller UNVERIFIED. NEVER use it for a
- * real access gate — anyone who can make your gate call fail (trivial: induce a
- * timeout) then bypasses it completely. It exists ONLY for soft, non-security
- * personalization where a missing verification must not degrade UX (e.g.
- * optionally showing a "verified" flourish). If the gate protects anything —
- * a route, a mint, an airdrop, a write — use the default `"throw"` or `"deny"`.
+ * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN, and is NEVER acceptable on a real
+ * gate. On ANY error (network blip, timeout, 5xx, auth failure, a malformed
+ * response) it fabricates a `passed: true` decision and admits the caller
+ * UNVERIFIED — so anyone who can make your gate call fail (trivial: induce a
+ * timeout) bypasses it completely. That makes it strictly WORSE than no gate for
+ * anything it is supposed to protect: 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). Constructing a guard with it logs a one-time `console.warn`. If the
+ * decision gates ANYTHING, use the default `"throw"` or `"deny"` (fail-closed).
  *
  * @example
  * ```ts

package/dist/gateClient.js

@@ -81,14 +81,16 @@ export async function checkGate(cfg, subject, policy) {
  * silently admitting an unverified caller. `onError: "deny"` instead resolves to
  * a clean `allowed: false` (fail-closed without a throw).
  *
- * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN. On ANY error (network blip,
- * timeout, 5xx, auth failure, a malformed response) it fabricates a
- * `passed: true` decision and admits the caller UNVERIFIED. NEVER use it for a
- * real access gate — anyone who can make your gate call fail (trivial: induce a
- * timeout) then bypasses it completely. It exists ONLY for soft, non-security
- * personalization where a missing verification must not degrade UX (e.g.
- * optionally showing a "verified" flourish). If the gate protects anything —
- * a route, a mint, an airdrop, a write — use the default `"throw"` or `"deny"`.
+ * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN, and is NEVER acceptable on a real
+ * gate. On ANY error (network blip, timeout, 5xx, auth failure, a malformed
+ * response) it fabricates a `passed: true` decision and admits the caller
+ * UNVERIFIED — so anyone who can make your gate call fail (trivial: induce a
+ * timeout) bypasses it completely. That makes it strictly WORSE than no gate for
+ * anything it is supposed to protect: 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). Constructing a guard with it logs a one-time `console.warn`. If the
+ * decision gates ANYTHING, use the default `"throw"` or `"deny"` (fail-closed).
  *
  * @example
  * ```ts
@@ -106,6 +108,10 @@ export async function checkGate(cfg, subject, policy) {
  */
 export function requireGate(cfg, policy, opts = {}) {
     const onError = opts.onError ?? "throw";
+    // Warn HARD (once) the moment a fail-open guard is built — `onError: "allow"`
+    // admits unverified callers on any error and must never guard anything real.
+    if (onError === "allow")
+        warnFailOpenOnce();
     return async (subject) => {
         try {
             const decision = await checkGate(cfg, subject, policy);
@@ -126,3 +132,16 @@ export function requireGate(cfg, policy, opts = {}) {
         }
     };
 }
+/** Process-wide latch so the fail-open warning fires at most once, not on every
+ *  guard construction. */
+let failOpenWarned = false;
+function warnFailOpenOnce() {
+    if (failOpenWarned)
+        return;
+    failOpenWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn("[@x1id/resolve] requireGate({ onError: \"allow\" }) FAILS OPEN: on any gate-call " +
+        "error it admits the caller UNVERIFIED. Never use it to protect a route, mint, " +
+        "airdrop, write, or allowlist — use the default \"throw\" or \"deny\" instead. " +
+        "(This warning is for soft personalization-only uses; it logs once.)");
+}

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  *
  * // bytes of @x1id/resolve/wasm/x1_resolve_wasm.wasm — see the README for loading
  * const wasm = await WasmResolver.fromBytes(wasmBytes);
- * // The @handle registry is on X1 testnet today; X1NS domains are on mainnet.
- * const r = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
+ * // The @handle registry and X1NS domains are on X1 mainnet (testnet works the same).
+ * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz", wasm });
  * const res = await r.resolve("@jack", { chain: "X1" });
  * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
  * ```
@@ -45,11 +45,13 @@ export * from "./register.js";
 export * from "./adminConfig.js";
 export * from "./lease.js";
 export * from "./accounts.js";
+export * from "./pause.js";
 export * from "./x402.js";
 export * from "./recordWrite.js";
 export * from "./clearRecords.js";
 export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
+export * from "./payment.js";
 export * from "./signin.js";
 export * from "./connect.js";
 export * from "./domainProof.js";

package/dist/index.js

@@ -6,8 +6,8 @@
  *
  * // bytes of @x1id/resolve/wasm/x1_resolve_wasm.wasm — see the README for loading
  * const wasm = await WasmResolver.fromBytes(wasmBytes);
- * // The @handle registry is on X1 testnet today; X1NS domains are on mainnet.
- * const r = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
+ * // The @handle registry and X1NS domains are on X1 mainnet (testnet works the same).
+ * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz", wasm });
  * const res = await r.resolve("@jack", { chain: "X1" });
  * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
  * ```
@@ -52,11 +52,13 @@ export * from "./lease.js";
 // the kind of drift docs/record-trust.md's "one implementation" rule
 // exists to prevent).
 export * from "./accounts.js";
+export * from "./pause.js";
 export * from "./x402.js";
 export * from "./recordWrite.js";
 export * from "./clearRecords.js";
 export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
+export * from "./payment.js";
 export * from "./signin.js";
 export * from "./connect.js";
 export * from "./domainProof.js";

package/dist/pause.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Emergency lockdown (global pause) — the off-chain READER for the registry's
+ * trailing `Config` pause region, plus transport-neutral builders for the two
+ * instructions that write it. The on-chain side lives in
+ * `programs/x1-handles/src/{state,lib}.rs` (PR feat/emergency-pause); this
+ * module only READS the region and BUILDS the instructions — it never changes
+ * the on-chain authority rules (pause = admin OR any guardian; unpause = admin
+ * only; both enforced by signature on-chain).
+ *
+ * # The pause region (raw byte layout, mirrored from `Config` in state.rs)
+ *
+ * It is a TRAILING region appended past the base `Config` struct at a FIXED raw
+ * byte offset — NOT a Borsh field, so it is read by absolute offset, never by
+ * walking the struct. Relative to the registry program's `Config::LEN` (445):
+ *
+ *   [445]      paused:   u8   (1 = locked down, 0 = open)
+ *   [446..454] paused_at: i64 LE (unix secs the lockdown last turned ON; 0 = never)
+ *   [454..614] pause_guardians: 5 × Pubkey (32 bytes each; all-zero = unused slot)
+ *
+ * Region length 169; the account grows to 614 bytes on first write. A `Config`
+ * created before this region existed (or any account shorter than 614 bytes)
+ * reads as NOT paused with NO guardians — exactly as the program's
+ * `require_not_locked` treats it. This reader therefore NEVER throws on a short
+ * account; it returns the open state.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return a
+ * transport-neutral {@link BuiltInstruction}; adapt to web3.js with the
+ * two-line snippet in `delegate.ts`'s module docs.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+/** Raw byte offset of the pause region — the registry program's `Config::LEN`.
+ *  The region is read by this ABSOLUTE offset, never by walking Borsh fields. */
+export declare const PAUSE_EXT_OFFSET = 445;
+/** Number of guardian slots in the region (mirrors `Config::PAUSE_GUARDIAN_SLOTS`). */
+export declare const PAUSE_GUARDIAN_SLOTS = 5;
+/** Length of the region: paused(1) + paused_at(8) + 5 × Pubkey(32) = 169. */
+export declare const PAUSE_EXT_LEN: number;
+/** First byte PAST the region. An account shorter than this has NO region. */
+export declare const PAUSE_EXT_END: number;
+/** Decoded pause state of the registry `Config` account. */
+export interface PauseState {
+    /** `true` iff the lockdown flag is set (byte 445 === 1). */
+    readonly paused: boolean;
+    /** Unix seconds the lockdown last turned on; `0n` when never / short account. */
+    readonly pausedAt: bigint;
+    /** The configured guardian pubkeys (base58), with all-zero (unused) slots dropped. */
+    readonly guardians: string[];
+}
+/**
+ * Decode the pause region from a registry `Config` account's raw data.
+ *
+ * Robust by contract: an account whose data is SHORTER than {@link PAUSE_EXT_END}
+ * (614) has no region and reads as `{ paused: false, pausedAt: 0n, guardians: [] }`
+ * — the same "absent region ⇒ open" rule the on-chain `require_not_locked`
+ * enforces. Never throws on a short or malformed-length account.
+ */
+export declare function readPauseState(data: Uint8Array): PauseState;
+/** `set_lockdown(paused: bool)` — Anchor discriminator (final, program author). */
+export declare const SET_LOCKDOWN_DISCRIMINATOR: Uint8Array;
+/** `set_pause_guardians(guardians: [Pubkey;5])` — Anchor discriminator (final). */
+export declare const SET_PAUSE_GUARDIANS_DISCRIMINATOR: Uint8Array;
+export interface SetLockdownParams {
+    readonly programId: AddressLike;
+    /** The signer — any guardian OR `Config.admin` for a PAUSE; `Config.admin`
+     *  ONLY for an UNPAUSE (the program enforces this by signature — the builder
+     *  does not, since it cannot know the account's admin/guardians). */
+    readonly caller: AddressLike;
+    /** The `["config"]` PDA (writable). */
+    readonly config: AddressLike;
+    /** The `["market_config"]` PDA (writable) — `set_lockdown` mirrors the flag
+     *  onto MarketConfig so listings/offers/auctions stop together. */
+    readonly marketConfig: AddressLike;
+    /** `true` = lock down, `false` = reopen. */
+    readonly paused: boolean;
+}
+/**
+ * Build `set_lockdown(paused)`. Accounts IN ORDER (mirrors lib.rs):
+ *   0 caller         (signer, writable)
+ *   1 config         (writable)  — ["config"]
+ *   2 market_config  (writable)  — ["market_config"]
+ *   3 system_program
+ * data = disc(8) ‖ paused(1 byte: 1 = lock / 0 = unlock).
+ */
+export declare function buildSetLockdownIx(p: SetLockdownParams): BuiltInstruction;
+export interface SetPauseGuardiansParams {
+    readonly programId: AddressLike;
+    /** `Config.admin` — the ONLY key the program accepts (admin-only). Signs; writable. */
+    readonly admin: AddressLike;
+    /** The `["config"]` PDA (writable). */
+    readonly config: AddressLike;
+    /** Exactly 5 guardian pubkeys in slot order; a zero address (or the system
+     *  program) marks an unused slot. */
+    readonly guardians: ReadonlyArray<AddressLike>;
+}
+/**
+ * Build `set_pause_guardians([Pubkey;5])`. Admin-only. Accounts IN ORDER:
+ *   0 admin   (signer, writable)
+ *   1 config  (writable)  — ["config"]
+ *   2 system_program
+ * data = disc(8) ‖ 5 × 32 raw pubkey bytes in order (fixed `[Pubkey;5]`, NO
+ * length prefix). Pass fewer than 5 to zero-fill the trailing slots.
+ */
+export declare function buildSetPauseGuardiansIx(p: SetPauseGuardiansParams): BuiltInstruction;

package/dist/pause.js

@@ -0,0 +1,152 @@
+/**
+ * Emergency lockdown (global pause) — the off-chain READER for the registry's
+ * trailing `Config` pause region, plus transport-neutral builders for the two
+ * instructions that write it. The on-chain side lives in
+ * `programs/x1-handles/src/{state,lib}.rs` (PR feat/emergency-pause); this
+ * module only READS the region and BUILDS the instructions — it never changes
+ * the on-chain authority rules (pause = admin OR any guardian; unpause = admin
+ * only; both enforced by signature on-chain).
+ *
+ * # The pause region (raw byte layout, mirrored from `Config` in state.rs)
+ *
+ * It is a TRAILING region appended past the base `Config` struct at a FIXED raw
+ * byte offset — NOT a Borsh field, so it is read by absolute offset, never by
+ * walking the struct. Relative to the registry program's `Config::LEN` (445):
+ *
+ *   [445]      paused:   u8   (1 = locked down, 0 = open)
+ *   [446..454] paused_at: i64 LE (unix secs the lockdown last turned ON; 0 = never)
+ *   [454..614] pause_guardians: 5 × Pubkey (32 bytes each; all-zero = unused slot)
+ *
+ * Region length 169; the account grows to 614 bytes on first write. A `Config`
+ * created before this region existed (or any account shorter than 614 bytes)
+ * reads as NOT paused with NO guardians — exactly as the program's
+ * `require_not_locked` treats it. This reader therefore NEVER throws on a short
+ * account; it returns the open state.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return a
+ * transport-neutral {@link BuiltInstruction}; adapt to web3.js with the
+ * two-line snippet in `delegate.ts`'s module docs.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Raw byte offset of the pause region — the registry program's `Config::LEN`.
+ *  The region is read by this ABSOLUTE offset, never by walking Borsh fields. */
+export const PAUSE_EXT_OFFSET = 445;
+/** Number of guardian slots in the region (mirrors `Config::PAUSE_GUARDIAN_SLOTS`). */
+export const PAUSE_GUARDIAN_SLOTS = 5;
+/** Length of the region: paused(1) + paused_at(8) + 5 × Pubkey(32) = 169. */
+export const PAUSE_EXT_LEN = 1 + 8 + 32 * PAUSE_GUARDIAN_SLOTS;
+/** First byte PAST the region. An account shorter than this has NO region. */
+export const PAUSE_EXT_END = PAUSE_EXT_OFFSET + PAUSE_EXT_LEN; // 614
+/**
+ * Decode the pause region from a registry `Config` account's raw data.
+ *
+ * Robust by contract: an account whose data is SHORTER than {@link PAUSE_EXT_END}
+ * (614) has no region and reads as `{ paused: false, pausedAt: 0n, guardians: [] }`
+ * — the same "absent region ⇒ open" rule the on-chain `require_not_locked`
+ * enforces. Never throws on a short or malformed-length account.
+ */
+export function readPauseState(data) {
+    if (data.length < PAUSE_EXT_END) {
+        return { paused: false, pausedAt: 0n, guardians: [] };
+    }
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const paused = data[PAUSE_EXT_OFFSET] === 1;
+    // paused_at: i64 LE at offset 446.
+    const pausedAt = dv.getBigInt64(PAUSE_EXT_OFFSET + 1, true);
+    // Five 32-byte pubkeys from offset 454; drop all-zero (unused) slots.
+    const guardians = [];
+    for (let i = 0; i < PAUSE_GUARDIAN_SLOTS; i++) {
+        const o = PAUSE_EXT_OFFSET + 9 + 32 * i;
+        const slot = data.subarray(o, o + 32);
+        let allZero = true;
+        for (let j = 0; j < slot.length; j++) {
+            if (slot[j] !== 0) {
+                allZero = false;
+                break;
+            }
+        }
+        if (allZero)
+            continue;
+        guardians.push(encodeBase58(slot));
+    }
+    return { paused, pausedAt, guardians };
+}
+// ===== Instruction builders ================================================
+//
+// Anchor instruction data = 8-byte discriminator ‖ Borsh-encoded args. The
+// discriminators are the program author's final values (pinned by a byte test
+// in sdk/test/pause.test.js), NOT re-derived here, so this module needs no
+// sha256. Derive the PDAs with your runtime's `findProgramAddress`:
+//   config        = ["config"]        under the registry program
+//   market_config = ["market_config"] under the registry program
+/** `set_lockdown(paused: bool)` — Anchor discriminator (final, program author). */
+export const SET_LOCKDOWN_DISCRIMINATOR = Uint8Array.from([
+    50, 46, 87, 85, 162, 169, 232, 61,
+]);
+/** `set_pause_guardians(guardians: [Pubkey;5])` — Anchor discriminator (final). */
+export const SET_PAUSE_GUARDIANS_DISCRIMINATOR = Uint8Array.from([
+    6, 7, 64, 90, 220, 50, 172, 166,
+]);
+/** The System Program id — the final account on both instructions. Not
+ *  re-exported (adminMarket.ts already owns that public name); internal here. */
+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));
+}
+/**
+ * Build `set_lockdown(paused)`. Accounts IN ORDER (mirrors lib.rs):
+ *   0 caller         (signer, writable)
+ *   1 config         (writable)  — ["config"]
+ *   2 market_config  (writable)  — ["market_config"]
+ *   3 system_program
+ * data = disc(8) ‖ paused(1 byte: 1 = lock / 0 = unlock).
+ */
+export function buildSetLockdownIx(p) {
+    const data = new Uint8Array(8 + 1);
+    data.set(SET_LOCKDOWN_DISCRIMINATOR, 0);
+    data[8] = p.paused ? 1 : 0;
+    const keys = [
+        { pubkey: toBase58(p.caller, "caller"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.marketConfig, "marketConfig"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM_ID, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `set_pause_guardians([Pubkey;5])`. Admin-only. Accounts IN ORDER:
+ *   0 admin   (signer, writable)
+ *   1 config  (writable)  — ["config"]
+ *   2 system_program
+ * data = disc(8) ‖ 5 × 32 raw pubkey bytes in order (fixed `[Pubkey;5]`, NO
+ * length prefix). Pass fewer than 5 to zero-fill the trailing slots.
+ */
+export function buildSetPauseGuardiansIx(p) {
+    if (p.guardians.length > PAUSE_GUARDIAN_SLOTS) {
+        throw new Error(`at most ${PAUSE_GUARDIAN_SLOTS} guardians, got ${p.guardians.length}`);
+    }
+    const data = new Uint8Array(8 + 32 * PAUSE_GUARDIAN_SLOTS);
+    data.set(SET_PAUSE_GUARDIANS_DISCRIMINATOR, 0);
+    for (let i = 0; i < p.guardians.length; i++) {
+        data.set(toBytes32(p.guardians[i], `guardians[${i}]`), 8 + 32 * i);
+    }
+    // Slots past guardians.length stay zero = unused.
+    const keys = [
+        { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM_ID, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/payment.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The ONE payment-resolution rule (W16, owner ruling 2026-10-07):
+ * **verified-record-else-owner, uniform on every payment surface.**
+ *
+ * A handle's per-chain address `Record` can be written by a record-editing
+ * DELEGATE, not just the owner — so an UNVERIFIED record must never receive
+ * money: a malicious delegate could silently redirect payments. On-chain
+ * VERIFICATION (`verify_record_svm` — the recorded address itself co-signed)
+ * is the guard, so the rule every pay surface shares is:
+ *
+ *   1. a LIVE, VERIFIED record for the payment chain → that record's address
+ *      (`basis: "verified-record"`). Staleness is judged first: a record from
+ *      a previous registration epoch or before a `clear_records` wipe never
+ *      counts, verified bit or not (docs/record-trust.md — the `stale` flag
+ *      records.ts already computes).
+ *   2. otherwise → the handle's CURRENT AUTHORITY (`basis: "owner"`):
+ *      `Handle.owner` untokenized, the pNFT holder once tokenized. An
+ *      unverified record is IGNORED, not an error.
+ *   3. no authority known either (e.g. a tokenized name whose holder could
+ *      not be located) → `null`: there is no honest payment address.
+ *
+ * Every surface that shows a "pay @name" flow must also SHOW the basis next
+ * to the resolved address before the user confirms ("verified X1 record" vs
+ * "owner wallet") — the rule is only safe when it is visible.
+ */
+import type { Chain } from "./types.js";
+/** Why `address` is the one to pay: a live on-chain-verified record for the
+ *  chain, or the handle's current authority (owner / NFT holder). */
+export type PaymentBasis = "verified-record" | "owner";
+export interface PaymentResolution {
+    /** The address a payment to this name must target. */
+    readonly address: string;
+    readonly basis: PaymentBasis;
+}
+/** The slice of a decoded record the rule needs — satisfied structurally by
+ *  the SDK's `HandleRecord` (records.ts) and the app's `DecodedRecord`. */
+export interface PaymentRecordLike {
+    /** Which chain the record's coin_type maps to (null = unknown coin type). */
+    readonly chain: Chain | null;
+    /** Human-readable address stored in the record. */
+    readonly address: string;
+    /** `Record.verified` as decoded — already forced false for stale records by
+     *  both decoders, but `stale` is re-checked here regardless. */
+    readonly verified: boolean;
+    /** The staleness verdict (updated_at vs registered_at / records_cleared_at). */
+    readonly stale: boolean;
+}
+/**
+ * Apply the rule. `records` may be the FULL decoded list (stale ones
+ * included — they are re-excluded here, never trusted on the `verified` bit
+ * alone). `authority` is the handle's CURRENT authority — `Handle.owner`
+ * untokenized, the pNFT holder tokenized — or `null` when it is unknown
+ * (tokenized, holder not found): then a missing verified record yields
+ * `null`, the honest "no payment address exists".
+ */
+export declare function paymentAddressFor(records: readonly PaymentRecordLike[], authority: string | null, chain?: Chain): PaymentResolution | null;
+/** The user-facing basis line, so every surface words it identically. */
+export declare function paymentBasisLabel(basis: PaymentBasis, chain?: Chain): string;

package/dist/payment.js

@@ -0,0 +1,45 @@
+/**
+ * The ONE payment-resolution rule (W16, owner ruling 2026-10-07):
+ * **verified-record-else-owner, uniform on every payment surface.**
+ *
+ * A handle's per-chain address `Record` can be written by a record-editing
+ * DELEGATE, not just the owner — so an UNVERIFIED record must never receive
+ * money: a malicious delegate could silently redirect payments. On-chain
+ * VERIFICATION (`verify_record_svm` — the recorded address itself co-signed)
+ * is the guard, so the rule every pay surface shares is:
+ *
+ *   1. a LIVE, VERIFIED record for the payment chain → that record's address
+ *      (`basis: "verified-record"`). Staleness is judged first: a record from
+ *      a previous registration epoch or before a `clear_records` wipe never
+ *      counts, verified bit or not (docs/record-trust.md — the `stale` flag
+ *      records.ts already computes).
+ *   2. otherwise → the handle's CURRENT AUTHORITY (`basis: "owner"`):
+ *      `Handle.owner` untokenized, the pNFT holder once tokenized. An
+ *      unverified record is IGNORED, not an error.
+ *   3. no authority known either (e.g. a tokenized name whose holder could
+ *      not be located) → `null`: there is no honest payment address.
+ *
+ * Every surface that shows a "pay @name" flow must also SHOW the basis next
+ * to the resolved address before the user confirms ("verified X1 record" vs
+ * "owner wallet") — the rule is only safe when it is visible.
+ */
+/**
+ * Apply the rule. `records` may be the FULL decoded list (stale ones
+ * included — they are re-excluded here, never trusted on the `verified` bit
+ * alone). `authority` is the handle's CURRENT authority — `Handle.owner`
+ * untokenized, the pNFT holder tokenized — or `null` when it is unknown
+ * (tokenized, holder not found): then a missing verified record yields
+ * `null`, the honest "no payment address exists".
+ */
+export function paymentAddressFor(records, authority, chain = "X1") {
+    const rec = records.find((r) => r.chain === chain && !r.stale && r.verified);
+    if (rec)
+        return { address: rec.address, basis: "verified-record" };
+    if (authority !== null)
+        return { address: authority, basis: "owner" };
+    return null;
+}
+/** The user-facing basis line, so every surface words it identically. */
+export function paymentBasisLabel(basis, chain = "X1") {
+    return basis === "verified-record" ? `verified ${chain} record` : "owner wallet";
+}

package/dist/scoped.d.ts

@@ -68,16 +68,21 @@ export declare function namespaceIsActive(data: Uint8Array): boolean;
  * dependency), and so tests can supply a deterministic fake.
  */
 export interface ScopedHandleDeriver {
-    /** The `["handle", label, name]` PDA under `programId`, base58. */
+    /** The `["handle", [label_len], label, name]` PDA under `programId`, base58
+     *  (H1: the label is length-prefixed so a scoped name never collides with a
+     *  bare `@<label><name>`). */
     scopedHandleKey(label: string, name: string, programId: string): Promise<string> | string;
 }
 /**
  * Build the default scoped-handle deriver using `@solana/web3.js`.
  *
- * Seeds are `["handle", label, name]` under the registry program — exactly the
- * order `tools/api`'s `scoped_handle_pda` and the program's
- * `register_under_namespace` use, so the derived PDA is the account the name
- * actually lives at. Prefers an INJECTED web3 module (robust under `file:` /
+ * Seeds are `["handle", [label_len], label, name]` under the registry program
+ * (H1, 2026-10-06: the label is LENGTH-PREFIXED with a single byte = its UTF-8
+ * byte length, so a scoped `name.tld` never derives the same address as a bare
+ * `@<label><name>` — e.g. `ck.ja` ≠ `@jack`). This MUST match byte-for-byte the
+ * program's `verify_handle_pda_core` / `register_under_namespace` and
+ * `tools/api`'s `scoped_handle_pda`, or resolution breaks. Prefers an INJECTED
+ * web3 module (robust under `file:` /
  * `npm link`, where a bare specifier resolves from THIS package's realpath, not
  * the consumer's); falls back to a dynamic import for a normal install.
  */

package/dist/scoped.js

@@ -93,10 +93,13 @@ export function namespaceIsActive(data) {
 /**
  * Build the default scoped-handle deriver using `@solana/web3.js`.
  *
- * Seeds are `["handle", label, name]` under the registry program — exactly the
- * order `tools/api`'s `scoped_handle_pda` and the program's
- * `register_under_namespace` use, so the derived PDA is the account the name
- * actually lives at. Prefers an INJECTED web3 module (robust under `file:` /
+ * Seeds are `["handle", [label_len], label, name]` under the registry program
+ * (H1, 2026-10-06: the label is LENGTH-PREFIXED with a single byte = its UTF-8
+ * byte length, so a scoped `name.tld` never derives the same address as a bare
+ * `@<label><name>` — e.g. `ck.ja` ≠ `@jack`). This MUST match byte-for-byte the
+ * program's `verify_handle_pda_core` / `register_under_namespace` and
+ * `tools/api`'s `scoped_handle_pda`, or resolution breaks. Prefers an INJECTED
+ * web3 module (robust under `file:` /
  * `npm link`, where a bare specifier resolves from THIS package's realpath, not
  * the consumer's); falls back to a dynamic import for a normal install.
  */
@@ -119,7 +122,10 @@ export async function makeScopedHandleDeriver(web3Module) {
     return {
         scopedHandleKey(label, name, programId) {
             const program = new web3.PublicKey(programId);
-            const [key] = web3.PublicKey.findProgramAddressSync([handleSeed, enc.encode(label), enc.encode(name)], program);
+            // H1: length-prefix the label with its UTF-8 BYTE length (matches Rust
+            // `label.len() as u8`; labels are a–z0–9- ≤ 16 bytes so a u8 suffices).
+            const labelBytes = enc.encode(label);
+            const [key] = web3.PublicKey.findProgramAddressSync([handleSeed, Uint8Array.of(labelBytes.length), labelBytes, enc.encode(name)], program);
             return key.toBase58();
         },
     };