@x1id/resolve 0.21.0 → 0.22.0

package/README.md

@@ -605,8 +605,10 @@ const requirements = buildX402Requirements({
   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",
+  reference: invoiceReference, // a unique base58 reference per invoice (the payment carries it)
 });
+// Buyer side for api.x1id.io: sign x402RedeemMessage(reference) with the paying
+// wallet and send it as payload.payerSig next to payload.signature.
 ```
 
 This package only builds the requirements object — it does not build, sign,

package/dist/adminConfig.d.ts

@@ -44,6 +44,18 @@ 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;
+/** `sha256("global:set_namespace_creation_fee")[0..8]` — sets
+ *  `Config.namespace_creation_fee_lamports` (u64, the permissionless
+ *  `create_namespace` TLD creation fee paid to treasury). */
+export declare const SET_NAMESPACE_CREATION_FEE_DISCRIMINATOR: Uint8Array;
+/** Byte offset of `Config.namespace_creation_fee_lamports` (u64 LE) in the
+ *  Config account data, including the 8-byte Anchor discriminator — mirrors
+ *  `Config::NAMESPACE_CREATION_FEE_LAMPORTS_OFFSET` (state.rs). */
+export declare const NAMESPACE_CREATION_FEE_LAMPORTS_OFFSET = 436;
+/** Decode `Config.namespace_creation_fee_lamports` from raw Config account
+ *  data. Returns null for a Config too short to carry the field (pre-v6
+ *  layout) — never a guessed default. */
+export declare function decodeNamespaceCreationFeeLamports(configData: Uint8Array): bigint | null;
 /** 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. */
@@ -54,10 +66,12 @@ export interface AdminScalarParams {
     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;
+    /** The integer arg (u64/i64 encoding is identical for a non-negative value).
+     *  A string must be plain decimal digits (lamports amounts beyond JS's safe
+     *  integer range arrive from the admin queue as decimal strings). */
+    readonly value: number | bigint | string;
 }
 /** Build any one-integer-arg AdminOnly setter (lease rate divisor, lease grace,
- *  recovery timelock, min/max commitment age). disc(8) + value as little-endian
+ *  recovery timelock, min/max commitment age, namespace creation fee). 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

@@ -84,6 +84,22 @@ export const SET_LEASE_GRACE_PERIOD_DISCRIMINATOR = Uint8Array.from([212, 2, 110
 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]);
+/** `sha256("global:set_namespace_creation_fee")[0..8]` — sets
+ *  `Config.namespace_creation_fee_lamports` (u64, the permissionless
+ *  `create_namespace` TLD creation fee paid to treasury). */
+export const SET_NAMESPACE_CREATION_FEE_DISCRIMINATOR = Uint8Array.from([158, 152, 239, 141, 143, 5, 75, 198]);
+/** Byte offset of `Config.namespace_creation_fee_lamports` (u64 LE) in the
+ *  Config account data, including the 8-byte Anchor discriminator — mirrors
+ *  `Config::NAMESPACE_CREATION_FEE_LAMPORTS_OFFSET` (state.rs). */
+export const NAMESPACE_CREATION_FEE_LAMPORTS_OFFSET = 436;
+/** Decode `Config.namespace_creation_fee_lamports` from raw Config account
+ *  data. Returns null for a Config too short to carry the field (pre-v6
+ *  layout) — never a guessed default. */
+export function decodeNamespaceCreationFeeLamports(configData) {
+    if (configData.length < NAMESPACE_CREATION_FEE_LAMPORTS_OFFSET + 8)
+        return null;
+    return new DataView(configData.buffer, configData.byteOffset, configData.byteLength).getBigUint64(NAMESPACE_CREATION_FEE_LAMPORTS_OFFSET, true);
+}
 /** 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. */
@@ -93,11 +109,18 @@ export const ADMIN_SCALAR_DISCRIMINATORS = {
     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,
+    set_namespace_creation_fee: SET_NAMESPACE_CREATION_FEE_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
+ *  recovery timelock, min/max commitment age, namespace creation fee). disc(8) + value as little-endian
  *  u64(8). The value must be a non-negative integer that fits u64. */
 export function buildAdminScalarSetterIx(p) {
+    if (typeof p.value === "string" && !/^\d{1,20}$/.test(p.value)) {
+        throw new Error(`value ${JSON.stringify(p.value)} is not a non-negative decimal integer`);
+    }
+    if (typeof p.value === "number" && !Number.isSafeInteger(p.value)) {
+        throw new Error(`value ${p.value} is not a safe integer`);
+    }
     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`);

package/dist/index.d.ts

@@ -126,4 +126,5 @@ export interface Resolver {
 export declare function createResolver(config: ResolverConfig): Resolver;
 export * from "./adminMarket.js";
 export * from "./namespaceOverride.js";
+export * from "./namespacePricing.js";
 export * from "./universal.js";

package/dist/index.js

@@ -816,6 +816,7 @@ export function createResolver(config) {
 }
 export * from "./adminMarket.js";
 export * from "./namespaceOverride.js";
+export * from "./namespacePricing.js";
 // The X1ID Universal Resolver (#8475): cross-namespace resolution (.sol via SNS,
 // .eth via ENS) alongside the native path. Additive — the native resolver above
 // is untouched; `createUniversalResolver` composes it with external adapters.

package/dist/namespacePricing.d.ts

@@ -0,0 +1,207 @@
+/**
+ * TLD creator pricing (docs/specs/tld-creator-pricing.md): the SDK side of a
+ * TLD creator's own price table for names under their TLD.
+ *
+ * - `["ns_pricing", label]` holds a `NamespacePricing` account: a flat lamport
+ *   price per length band (index = `tier_index(len)`: 0 = 1 char … 8 = 9 chars,
+ *   9 = 10+), written ONLY by the namespace creator via `set_namespace_pricing`.
+ * - `register_under_namespace_v2` (v1's accounts + the pricing PDA as the
+ *   first remaining account) charges that band FLAT (no launch ramp) when
+ *   the account exists, else the legacy root price (`Config.tier_lamports` ×
+ *   the time/volume ramp), and refuses to charge more than the buyer's
+ *   `max_price_lamports`.
+ * - The legacy `register_under_namespace` (v1) fails closed
+ *   (`NamespacePricingRequiresV2`, 6117) on any TLD whose creator opted in.
+ *
+ * {@link quoteScopedName} reproduces the program's price selection exactly, so
+ * pass its `lamports` as `maxPriceLamports` to {@link buildRegisterUnderNamespaceV2Ix}.
+ *
+ * Hand-rolled like the rest of this package: no Anchor client, no
+ * `@solana/web3.js` import, no `@types/node`. PDAs are derived through an
+ * INJECTED `find_program_address` (see {@link PdaFinder}) because this package
+ * never hand-rolls the ed25519 on-curve check.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+/** Seed prefix of the `["ns_pricing", label]` PDA. */
+export declare const NAMESPACE_PRICING_SEED = "ns_pricing";
+/** `NAMESPACE_TIER_FLOOR_LAMPORTS`: every creator tier must be >= 1 XNT. */
+export declare const NAMESPACE_TIER_FLOOR_LAMPORTS = 1000000000n;
+/** `NAMESPACE_TIER_MAX_LAMPORTS`: every creator tier must be <= 100,000,000 XNT. */
+export declare const NAMESPACE_TIER_MAX_LAMPORTS: bigint;
+/** Number of length bands (same banding as the root `Config.tier_lamports`). */
+export declare const NAMESPACE_TIER_COUNT = 10;
+/** `sha256("global:set_namespace_pricing")[0..8]`. */
+export declare const SET_NAMESPACE_PRICING_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:register_under_namespace_v2")[0..8]`. */
+export declare const REGISTER_UNDER_NAMESPACE_V2_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:NamespacePricing")[0..8]`. */
+export declare const NAMESPACE_PRICING_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** `Namespace::PRICING_FLAG_EXT_OFFSET` — the one-byte "creator pricing is on"
+ *  marker past the Anchor-allocated `Namespace` (8 + INIT_SPACE = 107). */
+export declare const NAMESPACE_PRICING_MARKER_OFFSET = 107;
+/** Program error codes added by this feature (6000 + variant index). */
+export declare const NAMESPACE_PRICING_ERRORS: {
+    readonly NamespacePricingMismatch: 6116;
+    readonly NamespacePricingRequiresV2: 6117;
+    readonly PriceExceedsMax: 6118;
+    readonly NamespaceTierBelowFloor: 6119;
+    readonly NamespaceTierAboveMax: 6120;
+};
+/** lib.rs `tier_index`: 1 char -> 0 … 10+ -> 9 (0 clamps to 0). */
+export declare function scopedTierIndex(len: number): number;
+/** lib.rs `price_now` (registration price), in bigint like the program's u128. */
+export declare function rootPriceNow(tierLamports: bigint, launchTs: bigint, nowSecs: bigint, totalHandlesSold: bigint): bigint;
+/** Problems with a creator tier table, or null when the program would accept
+ *  it (exactly `validate_namespace_tiers`). */
+export declare function namespaceTiersProblem(tiers: ReadonlyArray<bigint>): string | null;
+/** `find_program_address` — injected so this package never does curve math
+ *  itself. With web3.js: `(seeds, pid) => PublicKey.findProgramAddressSync(seeds, new PublicKey(pid))[0].toBase58()`. */
+export type PdaFinder = (seeds: Uint8Array[], programId: string) => Promise<string> | string;
+/** The seeds of `["ns_pricing", label]`. */
+export declare function namespacePricingSeeds(label: string): Uint8Array[];
+/** Derive the canonical `["ns_pricing", label]` PDA. */
+export declare function deriveNamespacePricingPda(label: string, programId: AddressLike, find: PdaFinder): Promise<string>;
+/** Decoded `NamespacePricing` account. */
+export interface NamespacePricing {
+    readonly version: number;
+    readonly bump: number;
+    /** Lamports per band, index = {@link scopedTierIndex}(len). */
+    readonly tierLamports: readonly bigint[];
+    readonly updatedAt: bigint;
+    readonly label: string;
+}
+/**
+ * Decode a `NamespacePricing` account's raw data (discriminator included):
+ * disc(8) | version(u8) | bump(u8) | tier_lamports([u64;10]) | updated_at(i64)
+ * | label(String). Returns null when the bytes are not a `NamespacePricing`.
+ */
+export declare function decodeNamespacePricing(data: Uint8Array): NamespacePricing | null;
+/** Whether a raw `Namespace` account carries the "creator pricing is on"
+ *  marker (any nonzero byte at offset 107; a shorter account = off). */
+export declare function namespaceHasPricingMarker(namespaceData: Uint8Array): boolean;
+export interface SetNamespacePricingParams {
+    readonly programId: AddressLike;
+    /** The namespace `creator` (signer, pays rent on first set). */
+    readonly creator: AddressLike;
+    /** `["namespace", label]`. */
+    readonly namespace: AddressLike;
+    /** `["ns_pricing", label]` ({@link deriveNamespacePricingPda}). */
+    readonly namespacePricing: AddressLike;
+    readonly label: string;
+    /** 10 lamport prices, index = {@link scopedTierIndex}(len). */
+    readonly tierLamports: ReadonlyArray<bigint>;
+}
+/**
+ * Build `set_namespace_pricing(label, tier_lamports)`. Accounts IN ORDER
+ * (`SetNamespacePricing`): creator(s,w), namespace(w), namespace_pricing(w),
+ * system_program. Validates the table client-side with the program's exact
+ * bounds so a bad table never reaches a wallet prompt.
+ */
+export declare function buildSetNamespacePricingIx(p: SetNamespacePricingParams): BuiltInstruction;
+export interface RegisterUnderNamespaceV2Params {
+    readonly programId: AddressLike;
+    /** `["ns_pricing", label]` — ALWAYS the canonical PDA, whether or not the
+     *  creator has set pricing (the program decides from its contents). */
+    readonly namespacePricing: AddressLike;
+    readonly payer: AddressLike;
+    readonly owner: AddressLike;
+    readonly config: AddressLike;
+    readonly treasury: AddressLike;
+    readonly namespace: AddressLike;
+    readonly creatorPayout: AddressLike;
+    /** `["handle", [label_len], label, name]`. */
+    readonly handle: AddressLike;
+    readonly mint: AddressLike;
+    readonly ownerTokenAccount: AddressLike;
+    readonly metadata: AddressLike;
+    readonly masterEdition: AddressLike;
+    readonly tokenRecord: AddressLike;
+    readonly collectionMint: AddressLike;
+    readonly collectionMetadata: AddressLike;
+    readonly collectionMasterEdition: AddressLike;
+    readonly collectionAuthority: AddressLike;
+    /** Canonical sub-name (`alice` in `alice.pepe`). */
+    readonly name: string;
+    /** 0 Human, 1 Merchant, 2 Org, 3 Agent. */
+    readonly handleType: number;
+    /** Buyer's ceiling: the tx fails (`PriceExceedsMax`) if the on-chain price
+     *  is higher. Pass {@link quoteScopedName}'s `lamports`. */
+    readonly maxPriceLamports: bigint;
+    /** OPTIONAL referral pair — both or neither. */
+    readonly integrator?: AddressLike;
+    readonly integratorAllowlist?: AddressLike;
+    /** OPTIONAL `["ns_minter", label, payer]` (invite-only, non-creator). */
+    readonly minterAuthorization?: AddressLike;
+}
+/**
+ * Build `register_under_namespace_v2(name, handle_type, max_price_lamports)`.
+ * Accounts IN ORDER: the exact v1 `RegisterUnderNamespace` list (payer(s,w),
+ * owner, config(w), treasury(w), namespace, creator_payout(w), handle(w),
+ * mint(w), owner_token_account(w), metadata(w), master_edition(w),
+ * token_record(w), collection_mint, collection_metadata(w),
+ * collection_master_edition, collection_authority, token_metadata_program,
+ * token_program, associated_token_program, system_program,
+ * sysvar_instructions), then the three optional slots ALWAYS present
+ * (integrator, integrator_allowlist, minter_authorization — each the program
+ * id when absent, Anchor's "explicitly None"), then `namespace_pricing` as
+ * `remaining_accounts[0]`. The program fails closed if it is missing or
+ * shifted.
+ */
+export declare function buildRegisterUnderNamespaceV2Ix(p: RegisterUnderNamespaceV2Params): BuiltInstruction;
+/** The program's root pricing inputs, read from `Config`. */
+export interface RootPricingInputs {
+    readonly launchTs: bigint;
+    readonly tierLamports: readonly bigint[];
+    readonly totalHandlesSold: bigint;
+}
+/** Read `launch_ts`, `tier_lamports` and `total_handles_sold` from raw Config bytes. */
+export declare function decodeRootPricingInputs(config: Uint8Array): RootPricingInputs | null;
+/**
+ * The price `register_under_namespace_v2` charges, from already-read state —
+ * `scoped_registration_price` in lib.rs: the creator's band flat when a table
+ * exists, else the root band × the ramp.
+ */
+export declare function scopedRegistrationPrice(pricing: NamespacePricing | null, root: RootPricingInputs, nameLen: number, nowSecs: bigint): bigint;
+export interface ScopedQuote {
+    /** Lamports `register_under_namespace_v2` will charge (pass as `maxPriceLamports`). */
+    readonly lamports: bigint;
+    /** `custom` = the creator's table; `fallback` = root tiers × ramp. */
+    readonly source: "custom" | "fallback";
+    readonly tierIndex: number;
+    /** The canonical `["ns_pricing", label]` PDA (pass to the v2 builder). */
+    readonly pricingAccount: string;
+    /** The creator's full table when `source === "custom"`. */
+    readonly pricing: NamespacePricing | null;
+}
+export interface QuoteScopedNameOptions {
+    readonly rpc: RpcFn;
+    readonly programId: AddressLike;
+    readonly find: PdaFinder;
+    /** Unix seconds; defaults to the local clock (the ramp moves per quarter, so
+     *  seconds of skew never matter for a fresh quote). */
+    readonly nowSecs?: bigint;
+}
+/**
+ * Quote `name.label` exactly like the program prices it (pricing-or-fallback).
+ * Throws when Config is missing, or when the pricing account exists but is not
+ * a valid `NamespacePricing` owned by the program (the program would refuse
+ * too), so a caller never shows a price the chain will not honour.
+ */
+export declare function quoteScopedName(label: string, name: string, opts: QuoteScopedNameOptions): Promise<ScopedQuote>;
+/**
+ * The instruction to SIMULATE (never send) to learn whether the deployed
+ * program has this feature: `set_namespace_pricing` with no accounts. An
+ * upgraded program recognizes the discriminator and fails account validation
+ * (e.g. 3005 `AccountNotEnoughKeys`); a pre-upgrade program fails with
+ * Anchor's `InstructionFallbackNotFound` (101). Interpret the simulation's
+ * `err` with {@link interpretNamespacePricingProbe}.
+ */
+export declare function buildNamespacePricingProbeIx(programId: AddressLike): BuiltInstruction;
+/**
+ * Read a `simulateTransaction` result's `value.err` for the probe tx (whose
+ * probe instruction is at `probeIndex`). `true` = the program knows the
+ * instruction; `false` = it does not, or the result is not the shape we
+ * expect (fail closed: hide the feature rather than show a broken button).
+ */
+export declare function interpretNamespacePricingProbe(err: unknown, probeIndex: number): boolean;

package/dist/namespacePricing.js

@@ -0,0 +1,378 @@
+/**
+ * TLD creator pricing (docs/specs/tld-creator-pricing.md): the SDK side of a
+ * TLD creator's own price table for names under their TLD.
+ *
+ * - `["ns_pricing", label]` holds a `NamespacePricing` account: a flat lamport
+ *   price per length band (index = `tier_index(len)`: 0 = 1 char … 8 = 9 chars,
+ *   9 = 10+), written ONLY by the namespace creator via `set_namespace_pricing`.
+ * - `register_under_namespace_v2` (v1's accounts + the pricing PDA as the
+ *   first remaining account) charges that band FLAT (no launch ramp) when
+ *   the account exists, else the legacy root price (`Config.tier_lamports` ×
+ *   the time/volume ramp), and refuses to charge more than the buyer's
+ *   `max_price_lamports`.
+ * - The legacy `register_under_namespace` (v1) fails closed
+ *   (`NamespacePricingRequiresV2`, 6117) on any TLD whose creator opted in.
+ *
+ * {@link quoteScopedName} reproduces the program's price selection exactly, so
+ * pass its `lamports` as `maxPriceLamports` to {@link buildRegisterUnderNamespaceV2Ix}.
+ *
+ * Hand-rolled like the rest of this package: no Anchor client, no
+ * `@solana/web3.js` import, no `@types/node`. PDAs are derived through an
+ * INJECTED `find_program_address` (see {@link PdaFinder}) because this package
+ * never hand-rolls the ed25519 on-curve check.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+// ---------------------------------------------------------------------------
+// constants (mirror programs/x1-handles/src/{lib,state}.rs)
+// ---------------------------------------------------------------------------
+/** Seed prefix of the `["ns_pricing", label]` PDA. */
+export const NAMESPACE_PRICING_SEED = "ns_pricing";
+/** `NAMESPACE_TIER_FLOOR_LAMPORTS`: every creator tier must be >= 1 XNT. */
+export const NAMESPACE_TIER_FLOOR_LAMPORTS = 1000000000n;
+/** `NAMESPACE_TIER_MAX_LAMPORTS`: every creator tier must be <= 100,000,000 XNT. */
+export const NAMESPACE_TIER_MAX_LAMPORTS = 100000000n * 1000000000n;
+/** Number of length bands (same banding as the root `Config.tier_lamports`). */
+export const NAMESPACE_TIER_COUNT = 10;
+/** `sha256("global:set_namespace_pricing")[0..8]`. */
+export const SET_NAMESPACE_PRICING_DISCRIMINATOR = Uint8Array.from([
+    245, 190, 192, 77, 94, 146, 50, 246,
+]);
+/** `sha256("global:register_under_namespace_v2")[0..8]`. */
+export const REGISTER_UNDER_NAMESPACE_V2_DISCRIMINATOR = Uint8Array.from([
+    233, 132, 213, 179, 60, 113, 18, 247,
+]);
+/** `sha256("account:NamespacePricing")[0..8]`. */
+export const NAMESPACE_PRICING_ACCOUNT_DISCRIMINATOR = Uint8Array.from([
+    197, 197, 26, 252, 150, 176, 211, 188,
+]);
+/** `Namespace::PRICING_FLAG_EXT_OFFSET` — the one-byte "creator pricing is on"
+ *  marker past the Anchor-allocated `Namespace` (8 + INIT_SPACE = 107). */
+export const NAMESPACE_PRICING_MARKER_OFFSET = 107;
+/** Program error codes added by this feature (6000 + variant index). */
+export const NAMESPACE_PRICING_ERRORS = {
+    NamespacePricingMismatch: 6116,
+    NamespacePricingRequiresV2: 6117,
+    PriceExceedsMax: 6118,
+    NamespaceTierBelowFloor: 6119,
+    NamespaceTierAboveMax: 6120,
+};
+/** Anchor's `InstructionFallbackNotFound`: the deployed program does not know
+ *  the instruction (i.e. it predates this feature). */
+const ANCHOR_INSTRUCTION_FALLBACK_NOT_FOUND = 101;
+// Root pricing curve — mirrors lib.rs `ramp_bps` / `quarters_elapsed` /
+// `compute_price` / `price_now` exactly (same constants as app/src/lib/x1/pricing.ts).
+const INTRO_START_BPS = 5000n;
+const INTRO_STEP_BPS = 1250n;
+const QUARTER_SECS = 91n * 24n * 60n * 60n;
+const VOLUME_START_BPS = 5000n;
+const VOLUME_STEP_BPS = 1250n;
+const VOLUME_STEP_COUNT = 500n;
+// Config byte offsets (state.rs): disc(8) admin(32) treasury(32) launch_ts(8)
+// tier_lamports(80) nft_tier_lamports(80) total_handles_sold(8) ...
+const CONFIG_LAUNCH_TS_OFFSET = 72;
+const CONFIG_TIERS_OFFSET = 80;
+const CONFIG_TOTAL_SOLD_OFFSET = 240;
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const TE = new TextEncoder();
+// ---------------------------------------------------------------------------
+// pure helpers
+// ---------------------------------------------------------------------------
+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));
+}
+function key(pubkey, what, isSigner, isWritable) {
+    return { pubkey: toBase58(pubkey, what), isSigner, isWritable };
+}
+function borshString(s) {
+    const b = TE.encode(s);
+    const out = new Uint8Array(4 + b.length);
+    new DataView(out.buffer).setUint32(0, b.length, true);
+    out.set(b, 4);
+    return out;
+}
+function u64le(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, n, true);
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((a, p) => a + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+/** lib.rs `tier_index`: 1 char -> 0 … 10+ -> 9 (0 clamps to 0). */
+export function scopedTierIndex(len) {
+    return Math.min(Math.max(len, 1), 10) - 1;
+}
+/** lib.rs `price_now` (registration price), in bigint like the program's u128. */
+export function rootPriceNow(tierLamports, launchTs, nowSecs, totalHandlesSold) {
+    const elapsed = nowSecs > launchTs ? nowSecs - launchTs : 0n;
+    const quarters = elapsed / QUARTER_SECS;
+    const ramp = (start, step, n) => {
+        const v = start + step * n;
+        return v > 10000n ? 10000n : v;
+    };
+    const timeBps = ramp(INTRO_START_BPS, INTRO_STEP_BPS, quarters);
+    const volumeBps = ramp(VOLUME_START_BPS, VOLUME_STEP_BPS, totalHandlesSold / VOLUME_STEP_COUNT);
+    return (tierLamports * timeBps * volumeBps) / 10000n / 10000n;
+}
+/** Problems with a creator tier table, or null when the program would accept
+ *  it (exactly `validate_namespace_tiers`). */
+export function namespaceTiersProblem(tiers) {
+    if (tiers.length !== NAMESPACE_TIER_COUNT)
+        return `expected ${NAMESPACE_TIER_COUNT} tiers, got ${tiers.length}`;
+    for (let i = 0; i < tiers.length; i++) {
+        const t = tiers[i];
+        if (t < NAMESPACE_TIER_FLOOR_LAMPORTS)
+            return `tier ${i} is below the 1 XNT protocol floor`;
+        if (t > NAMESPACE_TIER_MAX_LAMPORTS)
+            return `tier ${i} is above the 100,000,000 XNT protocol maximum`;
+    }
+    return null;
+}
+/** The seeds of `["ns_pricing", label]`. */
+export function namespacePricingSeeds(label) {
+    return [TE.encode(NAMESPACE_PRICING_SEED), TE.encode(label)];
+}
+/** Derive the canonical `["ns_pricing", label]` PDA. */
+export async function deriveNamespacePricingPda(label, programId, find) {
+    return find(namespacePricingSeeds(label), toBase58(programId, "programId"));
+}
+/**
+ * Decode a `NamespacePricing` account's raw data (discriminator included):
+ * disc(8) | version(u8) | bump(u8) | tier_lamports([u64;10]) | updated_at(i64)
+ * | label(String). Returns null when the bytes are not a `NamespacePricing`.
+ */
+export function decodeNamespacePricing(data) {
+    if (data.length < 8 + 1 + 1 + 80 + 8 + 4)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (data[i] !== NAMESPACE_PRICING_ACCOUNT_DISCRIMINATOR[i])
+            return null;
+    }
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const tierLamports = [];
+    for (let i = 0; i < NAMESPACE_TIER_COUNT; i++)
+        tierLamports.push(dv.getBigUint64(10 + 8 * i, true));
+    const updatedAt = dv.getBigInt64(90, true);
+    const labelLen = dv.getUint32(98, true);
+    if (data.length < 102 + labelLen)
+        return null;
+    let label;
+    try {
+        label = new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(102, 102 + labelLen));
+    }
+    catch {
+        return null;
+    }
+    return { version: data[8], bump: data[9], tierLamports, updatedAt, label };
+}
+/** Whether a raw `Namespace` account carries the "creator pricing is on"
+ *  marker (any nonzero byte at offset 107; a shorter account = off). */
+export function namespaceHasPricingMarker(namespaceData) {
+    const b = namespaceData[NAMESPACE_PRICING_MARKER_OFFSET];
+    return b !== undefined && b !== 0;
+}
+/**
+ * Build `set_namespace_pricing(label, tier_lamports)`. Accounts IN ORDER
+ * (`SetNamespacePricing`): creator(s,w), namespace(w), namespace_pricing(w),
+ * system_program. Validates the table client-side with the program's exact
+ * bounds so a bad table never reaches a wallet prompt.
+ */
+export function buildSetNamespacePricingIx(p) {
+    const problem = namespaceTiersProblem(p.tierLamports);
+    if (problem)
+        throw new Error(problem);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            key(p.creator, "creator", true, true),
+            key(p.namespace, "namespace", false, true),
+            key(p.namespacePricing, "namespacePricing", false, true),
+            key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ],
+        data: concat(SET_NAMESPACE_PRICING_DISCRIMINATOR, borshString(p.label), ...p.tierLamports.map(u64le)),
+    };
+}
+const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+const ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+const TOKEN_METADATA_PROGRAM = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s";
+const SYSVAR_INSTRUCTIONS = "Sysvar1nstructions1111111111111111111111111";
+/**
+ * Build `register_under_namespace_v2(name, handle_type, max_price_lamports)`.
+ * Accounts IN ORDER: the exact v1 `RegisterUnderNamespace` list (payer(s,w),
+ * owner, config(w), treasury(w), namespace, creator_payout(w), handle(w),
+ * mint(w), owner_token_account(w), metadata(w), master_edition(w),
+ * token_record(w), collection_mint, collection_metadata(w),
+ * collection_master_edition, collection_authority, token_metadata_program,
+ * token_program, associated_token_program, system_program,
+ * sysvar_instructions), then the three optional slots ALWAYS present
+ * (integrator, integrator_allowlist, minter_authorization — each the program
+ * id when absent, Anchor's "explicitly None"), then `namespace_pricing` as
+ * `remaining_accounts[0]`. The program fails closed if it is missing or
+ * shifted.
+ */
+export function buildRegisterUnderNamespaceV2Ix(p) {
+    if (!Number.isInteger(p.handleType) || p.handleType < 0 || p.handleType > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+    if (typeof p.maxPriceLamports !== "bigint" || p.maxPriceLamports < 0n || p.maxPriceLamports > 0xffffffffffffffffn) {
+        throw new Error("maxPriceLamports must be a u64 bigint");
+    }
+    if ((p.integrator === undefined) !== (p.integratorAllowlist === undefined)) {
+        throw new Error("integrator and integratorAllowlist must be supplied together");
+    }
+    const programId = toBase58(p.programId, "programId");
+    const none = () => ({ pubkey: programId, isSigner: false, isWritable: false });
+    const keys = [
+        key(p.payer, "payer", true, true),
+        key(p.owner, "owner", false, false),
+        key(p.config, "config", false, true),
+        key(p.treasury, "treasury", false, true),
+        key(p.namespace, "namespace", false, false),
+        key(p.creatorPayout, "creatorPayout", false, true),
+        key(p.handle, "handle", false, true),
+        key(p.mint, "mint", false, true),
+        key(p.ownerTokenAccount, "ownerTokenAccount", false, true),
+        key(p.metadata, "metadata", false, true),
+        key(p.masterEdition, "masterEdition", false, true),
+        key(p.tokenRecord, "tokenRecord", false, true),
+        key(p.collectionMint, "collectionMint", false, false),
+        key(p.collectionMetadata, "collectionMetadata", false, true),
+        key(p.collectionMasterEdition, "collectionMasterEdition", false, false),
+        key(p.collectionAuthority, "collectionAuthority", false, false),
+        key(TOKEN_METADATA_PROGRAM, "tokenMetadataProgram", false, false),
+        key(TOKEN_PROGRAM, "tokenProgram", false, false),
+        key(ASSOCIATED_TOKEN_PROGRAM, "associatedTokenProgram", false, false),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        key(SYSVAR_INSTRUCTIONS, "sysvarInstructions", false, false),
+        p.integrator !== undefined ? key(p.integrator, "integrator", false, true) : none(),
+        p.integratorAllowlist !== undefined ? key(p.integratorAllowlist, "integratorAllowlist", false, false) : none(),
+        p.minterAuthorization !== undefined ? key(p.minterAuthorization, "minterAuthorization", false, false) : none(),
+        key(p.namespacePricing, "namespacePricing", false, false),
+    ];
+    return {
+        programId,
+        keys,
+        data: concat(REGISTER_UNDER_NAMESPACE_V2_DISCRIMINATOR, borshString(p.name), Uint8Array.of(p.handleType), u64le(p.maxPriceLamports)),
+    };
+}
+/** Read `launch_ts`, `tier_lamports` and `total_handles_sold` from raw Config bytes. */
+export function decodeRootPricingInputs(config) {
+    if (config.length < CONFIG_TOTAL_SOLD_OFFSET + 8)
+        return null;
+    const dv = new DataView(config.buffer, config.byteOffset, config.byteLength);
+    const tierLamports = [];
+    for (let i = 0; i < NAMESPACE_TIER_COUNT; i++)
+        tierLamports.push(dv.getBigUint64(CONFIG_TIERS_OFFSET + 8 * i, true));
+    return {
+        launchTs: dv.getBigInt64(CONFIG_LAUNCH_TS_OFFSET, true),
+        tierLamports,
+        totalHandlesSold: dv.getBigUint64(CONFIG_TOTAL_SOLD_OFFSET, true),
+    };
+}
+/**
+ * The price `register_under_namespace_v2` charges, from already-read state —
+ * `scoped_registration_price` in lib.rs: the creator's band flat when a table
+ * exists, else the root band × the ramp.
+ */
+export function scopedRegistrationPrice(pricing, root, nameLen, nowSecs) {
+    const i = scopedTierIndex(nameLen);
+    if (pricing)
+        return pricing.tierLamports[i];
+    return rootPriceNow(root.tierLamports[i], root.launchTs, nowSecs, root.totalHandlesSold);
+}
+async function readAccount(rpc, address) {
+    const res = (await rpc("getAccountInfo", [address, { encoding: "base64", commitment: "confirmed" }]));
+    const v = res?.value;
+    if (!v)
+        return null;
+    const bin = atob(v.data[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    return { owner: v.owner, data };
+}
+/**
+ * Quote `name.label` exactly like the program prices it (pricing-or-fallback).
+ * Throws when Config is missing, or when the pricing account exists but is not
+ * a valid `NamespacePricing` owned by the program (the program would refuse
+ * too), so a caller never shows a price the chain will not honour.
+ */
+export async function quoteScopedName(label, name, opts) {
+    const programId = toBase58(opts.programId, "programId");
+    const [config, pricingAccount] = await Promise.all([
+        opts.find([TE.encode("config")], programId),
+        deriveNamespacePricingPda(label, programId, opts.find),
+    ]);
+    const [configAcct, pricingAcct] = await Promise.all([readAccount(opts.rpc, config), readAccount(opts.rpc, pricingAccount)]);
+    if (!configAcct)
+        throw new Error("registry Config not found");
+    const root = decodeRootPricingInputs(configAcct.data);
+    if (!root)
+        throw new Error("registry Config is too short to read pricing");
+    let pricing = null;
+    if (pricingAcct && pricingAcct.owner === programId) {
+        pricing = decodeNamespacePricing(pricingAcct.data);
+        if (!pricing)
+            throw new Error(`.${label} pricing account is not a valid NamespacePricing`);
+    }
+    const nowSecs = opts.nowSecs ?? BigInt(Math.floor(Date.now() / 1000));
+    const nameLen = TE.encode(name).length;
+    return {
+        lamports: scopedRegistrationPrice(pricing, root, nameLen, nowSecs),
+        source: pricing ? "custom" : "fallback",
+        tierIndex: scopedTierIndex(nameLen),
+        pricingAccount,
+        pricing,
+    };
+}
+// ---------------------------------------------------------------------------
+// upgrade probe
+// ---------------------------------------------------------------------------
+/**
+ * The instruction to SIMULATE (never send) to learn whether the deployed
+ * program has this feature: `set_namespace_pricing` with no accounts. An
+ * upgraded program recognizes the discriminator and fails account validation
+ * (e.g. 3005 `AccountNotEnoughKeys`); a pre-upgrade program fails with
+ * Anchor's `InstructionFallbackNotFound` (101). Interpret the simulation's
+ * `err` with {@link interpretNamespacePricingProbe}.
+ */
+export function buildNamespacePricingProbeIx(programId) {
+    return { programId: toBase58(programId, "programId"), keys: [], data: SET_NAMESPACE_PRICING_DISCRIMINATOR.slice() };
+}
+/**
+ * Read a `simulateTransaction` result's `value.err` for the probe tx (whose
+ * probe instruction is at `probeIndex`). `true` = the program knows the
+ * instruction; `false` = it does not, or the result is not the shape we
+ * expect (fail closed: hide the feature rather than show a broken button).
+ */
+export function interpretNamespacePricingProbe(err, probeIndex) {
+    if (!err || typeof err !== "object")
+        return false;
+    const ie = err.InstructionError;
+    if (!Array.isArray(ie) || ie.length !== 2 || ie[0] !== probeIndex)
+        return false;
+    const detail = ie[1];
+    // Anchor reports both outcomes as `Custom` codes; anything else is an
+    // unexpected shape and reads as "not supported".
+    if (typeof detail === "object" && detail !== null && typeof detail.Custom === "number") {
+        return detail.Custom !== ANCHOR_INSTRUCTION_FALLBACK_NOT_FOUND;
+    }
+    return false;
+}

package/dist/sha256.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Minimal synchronous SHA-256 (FIPS 180-4). This SDK is zero-dependency and
+ * cannot assume WebCrypto is present AND synchronous (`crypto.subtle.digest`
+ * is async), so the x402 request-reference derivation (x402.ts) uses this
+ * pure implementation. Cross-checked against node:crypto in sdk/test/x402.test.js.
+ */
+/** SHA-256 of `data` (bytes, or a string hashed as its UTF-8 encoding). */
+export declare function sha256(data: Uint8Array | string): Uint8Array;
+/** Lowercase hex of `bytes`. */
+export declare function toHex(bytes: Uint8Array): string;

package/dist/sha256.js

@@ -0,0 +1,77 @@
+/**
+ * Minimal synchronous SHA-256 (FIPS 180-4). This SDK is zero-dependency and
+ * cannot assume WebCrypto is present AND synchronous (`crypto.subtle.digest`
+ * is async), so the x402 request-reference derivation (x402.ts) uses this
+ * pure implementation. Cross-checked against node:crypto in sdk/test/x402.test.js.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** SHA-256 of `data` (bytes, or a string hashed as its UTF-8 encoding). */
+export function sha256(data) {
+    const msg = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const bitLen = BigInt(msg.length) * 8n;
+    const padded = new Uint8Array(Math.ceil((msg.length + 9) / 64) * 64);
+    padded.set(msg);
+    padded[msg.length] = 0x80;
+    const dv = new DataView(padded.buffer);
+    dv.setBigUint64(padded.length - 8, bitLen, false);
+    const H = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const W = new Uint32Array(64);
+    const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let t = 0; t < 16; t++)
+            W[t] = dv.getUint32(off + t * 4, false);
+        for (let t = 16; t < 64; t++) {
+            const w15 = W[t - 15];
+            const w2 = W[t - 2];
+            const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+            const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+            W[t] = (W[t - 16] + s0 + W[t - 7] + s1) >>> 0;
+        }
+        let a = H[0], b = H[1], c = H[2], d = H[3], e = H[4], f = H[5], g = H[6], h = H[7];
+        for (let t = 0; t < 64; t++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (h + S1 + ch + K[t] + W[t]) >>> 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        H[0] = (H[0] + a) >>> 0;
+        H[1] = (H[1] + b) >>> 0;
+        H[2] = (H[2] + c) >>> 0;
+        H[3] = (H[3] + d) >>> 0;
+        H[4] = (H[4] + e) >>> 0;
+        H[5] = (H[5] + f) >>> 0;
+        H[6] = (H[6] + g) >>> 0;
+        H[7] = (H[7] + h) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const odv = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        odv.setUint32(i * 4, H[i], false);
+    return out;
+}
+/** Lowercase hex of `bytes`. */
+export function toHex(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += b.toString(16).padStart(2, "0");
+    return s;
+}

package/dist/voucher.d.ts

@@ -25,18 +25,26 @@
  *   a bound recipient (audit S6 — open/recipient-less vouchers were removed as
  *   front-runnable; `claimSecretHash` is vestigial and rejected). An optional integrator referrer (the same trailing accounts as
  *   `register`, from `integrator.ts`) is snapshotted so the claim can split
- *   the escrow. `expiresAt` must be strictly in the future.
+ *   the escrow. `expiresAt` must be strictly in the future and at most
+ *   `MAX_VOUCHER_DURATION_SECS` (366 days) away (audit R4-A-2).
  * - `claim_voucher(name)` registers the handle, drawing the fee from the
  *   escrow (split integrator/treasury per the snapshot), and closes the
  *   voucher — rent back to the original payer. The `claimer` pays only the tx
- *   fee and the handle's rent, never the mint fee; a relayer may claim for a
- *   bound recipient. Supply the integrator wallet iff the voucher carries one.
+ *   fee and the handle's rent, never the mint fee. This untokenized claim must
+ *   be signed by the bound recipient (audit R4-A-3); a relayer uses
+ *   `claim_voucher_tokenized`. Supply the integrator wallet iff the voucher
+ *   carries one.
  * - `refund_voucher(name)` returns the whole escrow (+ rent) to the payer,
- *   payer-signed, only at/after `expiresAt`.
+ *   payer-signed, at/after `expiresAt`, or earlier once the name has been
+ *   registered by someone else (pass `handle`, audit R4-A-2).
  */
 import type { AddressLike, BuiltInstruction, InstructionKey } from "./delegate.js";
 /** Seed prefix of the voucher PDA: `["voucher", name]`. */
 export declare const VOUCHER_SEED = "voucher";
+/** Longest a voucher may stay open: `create_voucher` refuses an `expiresAt`
+ *  more than this many seconds ahead (`VoucherExpiryTooFar`, 6112; audit
+ *  R4-A-2). Mirrors lib.rs `MAX_VOUCHER_DURATION_SECS`. */
+export declare const MAX_VOUCHER_DURATION_SECS: number;
 /** Anchor instruction discriminator `sha256("global:create_voucher")[0..8]`. */
 export declare const CREATE_VOUCHER_DISCRIMINATOR: Uint8Array;
 /** Anchor instruction discriminator `sha256("global:claim_voucher")[0..8]`. */
@@ -130,8 +138,11 @@ export interface CreateVoucherParams {
 export declare function buildCreateVoucherIx(p: CreateVoucherParams): BuiltInstruction;
 export interface ClaimVoucherParams {
     readonly programId: AddressLike;
-    /** Pays the tx fee + the handle's rent (NOT the mint fee). Signer. May be a
-     *  relayer when the voucher binds a recipient. */
+    /** Pays the tx fee + the handle's rent (NOT the mint fee). Signer. For a
+     *  bound voucher this MUST be the recipient (audit R4-A-3,
+     *  `VoucherClaimNotRecipient` 6109): this untokenized claim skips the
+     *  bundled pNFT, so only the recipient may opt out of it. Relayers use
+     *  `buildClaimVoucherTokenizedIx`, which stays permissionless. */
     readonly claimer: AddressLike;
     readonly config: AddressLike;
     /** `Config.treasury`. */
@@ -160,8 +171,15 @@ export interface RefundVoucherParams {
     readonly payer: AddressLike;
     readonly voucher: AddressLike;
     readonly name: string;
+    /** The `["handle", name]` PDA (audit R4-A-2), appended as the trailing
+     *  optional account. When that handle is already registered (someone else
+     *  took the name, so the claim can never succeed) the payer may refund
+     *  BEFORE `expiresAt`. Omit to send the original two-account form. */
+    readonly handle?: AddressLike;
 }
-/** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
+/** Build `refund_voucher` — payer-signed. Valid at/after `expiresAt`, or
+ *  earlier when `handle` is passed and that name is already registered
+ *  (audit R4-A-2). */
 export declare function buildRefundVoucherIx(p: RefundVoucherParams): BuiltInstruction;
 /** `sha256("global:claim_voucher_tokenized")[0..8]`. */
 export declare const CLAIM_VOUCHER_TOKENIZED_DISCRIMINATOR: Uint8Array;

package/dist/voucher.js

@@ -25,18 +25,26 @@
  *   a bound recipient (audit S6 — open/recipient-less vouchers were removed as
  *   front-runnable; `claimSecretHash` is vestigial and rejected). An optional integrator referrer (the same trailing accounts as
  *   `register`, from `integrator.ts`) is snapshotted so the claim can split
- *   the escrow. `expiresAt` must be strictly in the future.
+ *   the escrow. `expiresAt` must be strictly in the future and at most
+ *   `MAX_VOUCHER_DURATION_SECS` (366 days) away (audit R4-A-2).
  * - `claim_voucher(name)` registers the handle, drawing the fee from the
  *   escrow (split integrator/treasury per the snapshot), and closes the
  *   voucher — rent back to the original payer. The `claimer` pays only the tx
- *   fee and the handle's rent, never the mint fee; a relayer may claim for a
- *   bound recipient. Supply the integrator wallet iff the voucher carries one.
+ *   fee and the handle's rent, never the mint fee. This untokenized claim must
+ *   be signed by the bound recipient (audit R4-A-3); a relayer uses
+ *   `claim_voucher_tokenized`. Supply the integrator wallet iff the voucher
+ *   carries one.
  * - `refund_voucher(name)` returns the whole escrow (+ rent) to the payer,
- *   payer-signed, only at/after `expiresAt`.
+ *   payer-signed, at/after `expiresAt`, or earlier once the name has been
+ *   registered by someone else (pass `handle`, audit R4-A-2).
  */
 import { encodeBase58, decodeBase58_32 } from "./base58.js";
 /** Seed prefix of the voucher PDA: `["voucher", name]`. */
 export const VOUCHER_SEED = "voucher";
+/** Longest a voucher may stay open: `create_voucher` refuses an `expiresAt`
+ *  more than this many seconds ahead (`VoucherExpiryTooFar`, 6112; audit
+ *  R4-A-2). Mirrors lib.rs `MAX_VOUCHER_DURATION_SECS`. */
+export const MAX_VOUCHER_DURATION_SECS = 366 * 24 * 60 * 60;
 /** Anchor instruction discriminator `sha256("global:create_voucher")[0..8]`. */
 export const CREATE_VOUCHER_DISCRIMINATOR = Uint8Array.from([22, 97, 32, 21, 104, 137, 188, 143]);
 /** Anchor instruction discriminator `sha256("global:claim_voucher")[0..8]`. */
@@ -231,20 +239,22 @@ export function buildClaimVoucherIx(p) {
     }
     return { programId: toBase58(p.programId, "programId"), keys, data };
 }
-/** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
+/** Build `refund_voucher` — payer-signed. Valid at/after `expiresAt`, or
+ *  earlier when `handle` is passed and that name is already registered
+ *  (audit R4-A-2). */
 export function buildRefundVoucherIx(p) {
     const name = encString(p.name);
     const data = new Uint8Array(8 + name.length);
     data.set(REFUND_VOUCHER_DISCRIMINATOR, 0);
     data.set(name, 8);
-    return {
-        programId: toBase58(p.programId, "programId"),
-        keys: [
-            { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
-            { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
-        ],
-        data,
-    };
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
+    ];
+    if (p.handle !== undefined) {
+        keys.push({ pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
 }
 // ===================== claim_voucher_tokenized (gift NFTs, #8335) =====================
 /** `sha256("global:claim_voucher_tokenized")[0..8]`. */

package/dist/x402.d.ts

@@ -21,12 +21,21 @@
  * its own SVM chain, but `@x402/core`'s reference client/facilitator only route
  * the `solana:*` scheme family — so to let ANY standard, unmodified x402 client
  * or wallet pay an x1id agent out of the box, X1 testnet uses the CAIP-30 form
- * keyed on X1's genesis. (Fortiswap's self-hosted X1 facilitator uses the
- * identical id.) An earlier release used a principled `"x1:<full-genesis>"`
+ * keyed on X1's genesis. x1id's X1 rail is standalone and self-verified: the
+ * buyer self-sponsors and broadcasts, and the seller checks the finalized
+ * transaction on chain itself; no external facilitator is involved. An
+ * earlier release used a principled `"x1:<full-genesis>"`
  * extension; it was OSS-incompatible, so this migrated to CAIP-30 —
  * {@link X1_LEGACY_TESTNET_NETWORK} is kept only for reading older manifests.
  * Verified against `getGenesisHash` (full hash
  * `C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho`).
+ *
+ * # HTTP headers (x402 v2 transport)
+ *
+ * api.x1id.io sends the 402 body also as `PAYMENT-REQUIRED` (base64 JSON),
+ * accepts the payment in `PAYMENT-SIGNATURE` (base64 JSON; the v1 name
+ * `X-PAYMENT` still works), and returns `PAYMENT-RESPONSE` plus the v1
+ * `X-PAYMENT-RESPONSE` on success.
  */
 /** X1 testnet's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
  *  genesis hash — so unmodified OSS x402 clients route to it (#8325). */
@@ -72,9 +81,23 @@ export interface X402PaymentRequirements {
          *  no sponsor (see docs/x402.md): this SDK always sets it to the
          *  BUYER's own address (self-sponsored, no facilitator, no custody). */
         readonly feePayer: string;
-        /** UTF-8, <=256 bytes. Lets a seller correlate the on-chain payment to
-         *  an invoice without a unique deposit address per sale. */
-        readonly memo?: string;
+        /** Reference-key mode (api.x1id.io, R3-x402-1): a base58 pubkey derived
+         *  from the request + challenge nonce + payer (see
+         *  {@link deriveX402Reference}). The buyer appends it to the
+         *  TransferChecked instruction as one extra READ-ONLY, NON-SIGNER account.
+         *  Nobody holds a key for it. */
+        readonly reference?: string;
+        /** Hex SHA-256 of the canonical request the challenge was issued for
+         *  ({@link x402RequestHash}). Informational: lets a client confirm it is
+         *  about to pay for the request it will actually send. */
+        readonly requestHash?: string;
+        /** R4-D-1 payer-signed redemption (api.x1id.io): the exact UTF-8 message
+         *  the bound payer signs (ed25519, `signMessage`) to redeem this challenge
+         *  ({@link x402RedeemMessage}). The base58 signature goes in the payment
+         *  payload as `payload.payerSig`. The on-chain payment is public once it
+         *  lands; this signature is what proves the REDEEMER is the payer, so a
+         *  front-runner who copies the transaction signature cannot redeem it. */
+        readonly redeemMessage?: string;
         readonly recentBlockhash?: string;
         readonly lastValidBlockHeight?: string;
     };
@@ -97,6 +120,10 @@ export interface X402PaymentPayload {
     };
 }
 export interface BuildX402RequirementsParams {
+    /** Reference-key mode: the derived reference pubkey + request hash
+     *  ({@link deriveX402Reference}, {@link x402RequestHash}). */
+    readonly reference?: string;
+    readonly requestHash?: string;
     /** The recipient's base58 address. */
     readonly payTo: string;
     /** The SPL/Token-2022 mint's base58 address. */
@@ -114,7 +141,6 @@ export interface BuildX402RequirementsParams {
      *  default. Pass {@link X1_TESTNET_NETWORK} for testnet. */
     readonly network?: string;
     readonly maxTimeoutSeconds?: number;
-    readonly memo?: string;
     readonly recentBlockhash?: string;
     readonly lastValidBlockHeight?: string;
 }
@@ -128,3 +154,41 @@ export declare function buildX402Requirements(p: BuildX402RequirementsParams): X
 /** Parse a 402 response body, returning null if it doesn't look like one
  *  (missing/wrong `x402Version`, `accepts` not an array). Never throws. */
 export declare function parseX402Response(body: unknown): X402PaymentRequiredResponse | null;
+/** Domain-separation tag for the reference preimage. */
+export declare const X402_REFERENCE_DOMAIN = "x1id-x402-ref:v1|api.x1id.io/dev-api";
+/** SHA-256("") in hex — the body hash of a GET/HEAD or empty body. */
+export declare const X402_EMPTY_BODY_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/** Canonicalise a URL path (see the section docs). */
+export declare function canonicalizeX402Path(path: string): string;
+/** Canonicalise a query string (with or without the leading "?"). */
+export declare function canonicalizeX402Query(query: string): string;
+export interface X402RequestInput {
+    /** HTTP method; uppercased. */
+    readonly method: string;
+    /** The request target: a path with optional `?query` and `#fragment`, or an
+     *  absolute URL (scheme + host are dropped). */
+    readonly url: string;
+    /** The exact body bytes (a string is hashed as UTF-8). Ignored for GET/HEAD. */
+    readonly body?: Uint8Array | string | null;
+}
+/** The canonical request string (see the section docs). */
+export declare function canonicalX402Request(req: X402RequestInput): string;
+/** Hex SHA-256 of {@link canonicalX402Request} — `accepts[].extra.requestHash`. */
+export declare function x402RequestHash(req: X402RequestInput): string;
+/** Domain-separation tag for the payer-signed redemption message (R4-D-1). */
+export declare const X402_REDEEM_DOMAIN = "x1id-x402-redeem:v1|api.x1id.io/dev-api";
+/**
+ * R4-D-1: the message the bound payer signs to redeem a challenge — over its
+ * `accepts[].extra.reference`, which is single-use and already bound
+ * (server-side) to the endpoint, the exact request and the payer, so the
+ * signature cannot be replayed onto another challenge. Sent as base58 in
+ * `payload.payerSig`. The 402 also carries it verbatim as
+ * `accepts[].extra.redeemMessage`.
+ */
+export declare function x402RedeemMessage(reference: string): string;
+/** Derive the base58 reference pubkey for a request + challenge nonce + payer. */
+export declare function deriveX402Reference(p: {
+    readonly canonicalRequest: string;
+    readonly nonce: string;
+    readonly payer: string;
+}): string;

package/dist/x402.js

@@ -21,13 +21,24 @@
  * its own SVM chain, but `@x402/core`'s reference client/facilitator only route
  * the `solana:*` scheme family — so to let ANY standard, unmodified x402 client
  * or wallet pay an x1id agent out of the box, X1 testnet uses the CAIP-30 form
- * keyed on X1's genesis. (Fortiswap's self-hosted X1 facilitator uses the
- * identical id.) An earlier release used a principled `"x1:<full-genesis>"`
+ * keyed on X1's genesis. x1id's X1 rail is standalone and self-verified: the
+ * buyer self-sponsors and broadcasts, and the seller checks the finalized
+ * transaction on chain itself; no external facilitator is involved. An
+ * earlier release used a principled `"x1:<full-genesis>"`
  * extension; it was OSS-incompatible, so this migrated to CAIP-30 —
  * {@link X1_LEGACY_TESTNET_NETWORK} is kept only for reading older manifests.
  * Verified against `getGenesisHash` (full hash
  * `C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWwT5iTdeaviDho`).
+ *
+ * # HTTP headers (x402 v2 transport)
+ *
+ * api.x1id.io sends the 402 body also as `PAYMENT-REQUIRED` (base64 JSON),
+ * accepts the payment in `PAYMENT-SIGNATURE` (base64 JSON; the v1 name
+ * `X-PAYMENT` still works), and returns `PAYMENT-RESPONSE` plus the v1
+ * `X-PAYMENT-RESPONSE` on success.
  */
+import { encodeBase58 } from "./base58.js";
+import { sha256, toHex } from "./sha256.js";
 /** X1 testnet's x402 network id — CAIP-30 `"solana:" + first 32 chars of the
  *  genesis hash — so unmodified OSS x402 clients route to it (#8325). */
 export const X1_TESTNET_NETWORK = "solana:C7ucgdDEhxLTpXHhWSZxavSVmaNTUJWw";
@@ -71,12 +82,17 @@ export function buildX402Requirements(p) {
     if (!/^\d+$/.test(p.amount)) {
         throw new Error("amount must be a decimal string of smallest units (e.g. \"1000000\")");
     }
-    if (p.memo !== undefined && new TextEncoder().encode(p.memo).length > 256) {
-        throw new Error("memo must be <=256 UTF-8 bytes");
-    }
     const extra = { feePayer: p.buyer };
-    if (p.memo !== undefined)
-        extra.memo = p.memo;
+    if (p.reference !== undefined) {
+        if (!PUBKEY_RE.test(p.reference))
+            throw new Error("reference must be a base58 address");
+        extra.reference = p.reference;
+    }
+    if (p.requestHash !== undefined) {
+        if (!/^[0-9a-f]{64}$/.test(p.requestHash))
+            throw new Error("requestHash must be 64 lowercase hex chars");
+        extra.requestHash = p.requestHash;
+    }
     if (p.recentBlockhash !== undefined) {
         extra.recentBlockhash = p.recentBlockhash;
     }
@@ -103,3 +119,138 @@ export function parseX402Response(body) {
         return null;
     return { x402Version: X402_VERSION, accepts: b.accepts };
 }
+// ── Request-bound reference keys (api.x1id.io R3-x402-1) ───────────────────────
+//
+// A 402 challenge from api.x1id.io binds the payment to the EXACT request it
+// was issued for. The server derives a `reference` pubkey from the canonical
+// request, the challenge nonce and the payer; the buyer appends it to the
+// TransferChecked instruction as an extra read-only, non-signer account (SPL
+// Token ignores extra accounts for a single-owner transfer), ~6.6k CU per
+// payment. Nobody signs with the reference; it is not a keypair or a PDA, just
+// 32 hash bytes read as an address.
+//
+// Canonical request (one UTF-8 string, "\n"-separated, no trailing newline):
+//
+//   METHOD          uppercased ("GET", "POST")
+//   path            split on "/", each segment percent-decoded then re-encoded
+//                   per RFC 3986 (unreserved A-Z a-z 0-9 - . _ ~ literal, every
+//                   other byte %XX uppercase). No trailing-slash folding, case
+//                   PRESERVED: /v1/resolve/@Alice and /v1/resolve/@alice are
+//                   DIFFERENT requests (both canonicalise "@" to %40).
+//   query           split on "&" (empty parts dropped), each "k=v" split on the
+//                   first "=" ("k" alone == "k="), "+" read as a space, both
+//                   sides percent-decoded then re-encoded as above, sorted by
+//                   (key, value) on the encoded strings, duplicates KEPT, joined
+//                   with "&". "" when there is no query. No fragment.
+//   bodyHash        lowercase hex SHA-256 of the exact body bytes; GET/HEAD or
+//                   no body = SHA-256("") = e3b0c442…b855.
+//
+// Scheme and host are excluded (the domain is fixed by the tag below).
+//
+//   requestHash = hex(SHA-256(canonical))
+//   reference   = base58(SHA-256(utf8(X402_REFERENCE_DOMAIN + "\n" + canonical
+//                                       + "\n" + nonce + "\n" + payer)))
+/** Domain-separation tag for the reference preimage. */
+export const X402_REFERENCE_DOMAIN = "x1id-x402-ref:v1|api.x1id.io/dev-api";
+/** SHA-256("") in hex — the body hash of a GET/HEAD or empty body. */
+export const X402_EMPTY_BODY_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+function isUnreserved(b) {
+    return ((b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || (b >= 0x30 && b <= 0x39) ||
+        b === 0x2d || b === 0x2e || b === 0x5f || b === 0x7e);
+}
+function hexVal(c) {
+    if (c >= 0x30 && c <= 0x39)
+        return c - 0x30;
+    if (c >= 0x41 && c <= 0x46)
+        return c - 0x37;
+    if (c >= 0x61 && c <= 0x66)
+        return c - 0x57;
+    return -1;
+}
+/** Percent-decode to raw bytes. A `%` not followed by two hex digits is kept
+ *  literally (decoding never throws). */
+function pctDecode(s, plusIsSpace) {
+    const raw = new TextEncoder().encode(s);
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw[i];
+        if (c === 0x25 && i + 2 < raw.length) {
+            const hi = hexVal(raw[i + 1]);
+            const lo = hexVal(raw[i + 2]);
+            if (hi >= 0 && lo >= 0) {
+                out.push(hi * 16 + lo);
+                i += 2;
+                continue;
+            }
+        }
+        out.push(plusIsSpace && c === 0x2b ? 0x20 : c);
+    }
+    return new Uint8Array(out);
+}
+function pctEncode(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += isUnreserved(b) ? String.fromCharCode(b) : "%" + b.toString(16).toUpperCase().padStart(2, "0");
+    return s;
+}
+/** Canonicalise a URL path (see the section docs). */
+export function canonicalizeX402Path(path) {
+    const p = path === "" ? "/" : path;
+    return p
+        .split("/")
+        .map((seg) => pctEncode(pctDecode(seg, false)))
+        .join("/");
+}
+/** Canonicalise a query string (with or without the leading "?"). */
+export function canonicalizeX402Query(query) {
+    const q = query.startsWith("?") ? query.slice(1) : query;
+    const pairs = [];
+    for (const part of q.split("&")) {
+        if (part === "")
+            continue;
+        const eq = part.indexOf("=");
+        const k = eq === -1 ? part : part.slice(0, eq);
+        const v = eq === -1 ? "" : part.slice(eq + 1);
+        pairs.push([pctEncode(pctDecode(k, true)), pctEncode(pctDecode(v, true))]);
+    }
+    pairs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+    return pairs.map(([k, v]) => `${k}=${v}`).join("&");
+}
+/** The canonical request string (see the section docs). */
+export function canonicalX402Request(req) {
+    const method = req.method.toUpperCase();
+    let target = req.url;
+    const abs = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/?#]*/.exec(target);
+    if (abs)
+        target = target.slice(abs[0].length);
+    const hashAt = target.indexOf("#");
+    if (hashAt !== -1)
+        target = target.slice(0, hashAt);
+    const qAt = target.indexOf("?");
+    const path = qAt === -1 ? target : target.slice(0, qAt);
+    const query = qAt === -1 ? "" : target.slice(qAt + 1);
+    const noBody = method === "GET" || method === "HEAD" || req.body === undefined || req.body === null;
+    const bodyHash = noBody ? X402_EMPTY_BODY_HASH : toHex(sha256(req.body));
+    return `${method}\n${canonicalizeX402Path(path)}\n${canonicalizeX402Query(query)}\n${bodyHash}`;
+}
+/** Hex SHA-256 of {@link canonicalX402Request} — `accepts[].extra.requestHash`. */
+export function x402RequestHash(req) {
+    return toHex(sha256(canonicalX402Request(req)));
+}
+/** Domain-separation tag for the payer-signed redemption message (R4-D-1). */
+export const X402_REDEEM_DOMAIN = "x1id-x402-redeem:v1|api.x1id.io/dev-api";
+/**
+ * R4-D-1: the message the bound payer signs to redeem a challenge — over its
+ * `accepts[].extra.reference`, which is single-use and already bound
+ * (server-side) to the endpoint, the exact request and the payer, so the
+ * signature cannot be replayed onto another challenge. Sent as base58 in
+ * `payload.payerSig`. The 402 also carries it verbatim as
+ * `accepts[].extra.redeemMessage`.
+ */
+export function x402RedeemMessage(reference) {
+    return `${X402_REDEEM_DOMAIN}\nreference:${reference}`;
+}
+/** Derive the base58 reference pubkey for a request + challenge nonce + payer. */
+export function deriveX402Reference(p) {
+    return encodeBase58(sha256(`${X402_REFERENCE_DOMAIN}\n${p.canonicalRequest}\n${p.nonce}\n${p.payer}`));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",