@x1id/resolve 0.21.0 → 0.23.0

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]`. */