@x1id/resolve 0.9.0 → 0.11.0

package/dist/domainProof.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Independent, re-verifiable domain->wallet proof via DNS-over-HTTPS (#8318,
+ * Approach C — the "auditable attestor" honesty upgrade).
+ *
+ * # Why this exists
+ *
+ * A `dns`-kind {@link import("./attestation.js").HandleAttestation} records only
+ * that x1id's admin-rotatable attestor key *signed off* on an off-chain DNS
+ * lookup ("attestation.ts" says this plainly): the chain stores the attestor's
+ * say-so, not a proof. The fully-trustless answers (an on-chain DNSSEC verifier,
+ * or a zkTLS proof — Approaches A/B in `docs/trustless-domain-proof-plan.md`)
+ * are BLOCKED on this X1 fork because the runtime does not have the crypto
+ * primitives they need active (`big_mod_exp` / `secp256r1` / `alt_bn128` are all
+ * feature-gated off). Until one of those lands, this module is the shippable
+ * middle ground: it lets ANYONE independently re-resolve the domain's DNS record
+ * and confirm the binding, so the attestor can no longer lie *undetected*. Trust
+ * moves from "the x1id attestor" to "DNS + the domain owner" — a real, cheap
+ * upgrade that needs no on-chain change.
+ *
+ * It is dependency-free and runs in both the browser and Node: a DoH query is a
+ * plain HTTPS GET, and the JSON shape ("application/dns-json", the Cloudflare /
+ * Google convention) is parsed by hand, like the rest of this package.
+ *
+ * # The TXT record convention (the interoperability contract)
+ *
+ * A domain owner proves control of `<domain>` by publishing a TXT record at the
+ * name **`_x1id.<domain>`** whose value is:
+ *
+ *     x1id-wallet=<base58 wallet pubkey>
+ *
+ * - The prefix is the exported {@link TXT_BINDING_PREFIX} (`x1id-wallet=`).
+ * - `<base58 wallet pubkey>` is the 32-byte X1/SVM wallet address, base58, that
+ *   the domain is bound to (the handle's authority wallet). Multiple TXT records
+ *   under the same name are allowed — a domain may bind more than one wallet
+ *   (e.g. during a key rotation); {@link resolveDomainBinding} returns them all.
+ * - A single TXT record split into several character-strings (RFC 1035 §3.3.14 /
+ *   RFC 7208 §3.3) is concatenated with no separator before the prefix is
+ *   matched, exactly as a mail SPF/DKIM verifier would.
+ *
+ * This is the contract a domain owner follows, so it is deliberately simple and
+ * stable. It mirrors the `_dnslink`/`_atproto`/`_domainkey` underscore-prefixed
+ * convention rather than putting x1id data on the apex TXT (which would collide
+ * with SPF/verification tokens from every other service).
+ *
+ * # NOTE — the paired attestor-side follow-up (NOT done here)
+ *
+ * This SDK-only change gives verifiers the re-check primitive. The *other* half
+ * of Approach C — having the attestor publish the exact `_x1id.<domain>` TXT it
+ * checked inside the attestation's `evidence_hash` preimage bundle, so a
+ * back-dated attestation whose TXT was later removed is still disprovable — is a
+ * change to the admin-api attest tooling (`tools/`), tracked as a FOLLOW-UP. See
+ * `docs/trustless-domain-proof-plan.md` §4. Until that ships,
+ * {@link verifyDomainBinding} can only confirm a binding that is *still live* in
+ * DNS; it cannot audit a removed one.
+ */
+import type { RpcFn } from "./accounts.js";
+/** The canonical prefix of the `_x1id.<domain>` TXT binding value. A TXT string
+ *  that (after character-string concatenation) starts with this, followed by a
+ *  valid base58 32-byte address, is an x1id binding record. */
+export declare const TXT_BINDING_PREFIX = "x1id-wallet=";
+/** The DNS label prefixed to a domain to locate its x1id binding TXT records —
+ *  the query name is `${TXT_NAME_PREFIX}.<domain>`. */
+export declare const TXT_NAME_PREFIX = "_x1id";
+/** Built-in DoH endpoints (both speak the `application/dns-json` shape). */
+declare const DOH_PROVIDERS: Readonly<{
+    readonly cloudflare: "https://cloudflare-dns.com/dns-query";
+    readonly google: "https://dns.google/resolve";
+}>;
+export interface DomainProofOptions {
+    /** Which built-in DoH provider to use when {@link dohUrl} is not given.
+     *  Default `"cloudflare"`. */
+    readonly provider?: keyof typeof DOH_PROVIDERS;
+    /** A full DoH endpoint base URL (overrides {@link provider}), e.g. a
+     *  self-hosted resolver. The query string (`?name=...&type=TXT`) is appended;
+     *  a URL that already has query params is respected (`&` is used). Must speak
+     *  the `application/dns-json` response shape. */
+    readonly dohUrl?: string;
+    /** `fetch` override — inject one in tests (return canned DoH JSON) or to use a
+     *  custom transport. Defaults to `globalThis.fetch`. */
+    readonly fetchImpl?: typeof fetch;
+    /** Abort the DoH request after this many ms. Default 6000. */
+    readonly timeoutMs?: number;
+}
+/** The outcome of resolving a domain's `_x1id` TXT bindings. `ok` is about the
+ *  LOOKUP succeeding, not about any wallet being found: a domain that simply has
+ *  no binding is `ok: true` with an empty `wallets`. `ok: false` means the DNS
+ *  query itself failed (network, timeout, DoH error) and the answer is unknown —
+ *  never a throw. */
+export interface DomainBindingResult {
+    /** The DNS lookup completed and its answer was parsed. */
+    readonly ok: boolean;
+    /** The domain queried (lowercased, canonical). */
+    readonly domain: string;
+    /** Every distinct wallet the `_x1id.<domain>` TXT records bind, base58
+     *  (canonical spelling), first-seen order, de-duplicated. Empty when the
+     *  domain publishes no valid binding (or when `ok` is false). */
+    readonly wallets: string[];
+    /** Why the lookup failed, or a note when it succeeded with nothing usable.
+     *  Absent on a clean success that found bindings. */
+    readonly reason?: string;
+}
+/**
+ * Resolve the wallet(s) a domain binds via its `_x1id.<domain>` TXT records,
+ * independently of x1id's attestor — a DoH GET, parsed and validated defensively.
+ *
+ * Never throws: a network failure, timeout, or malformed answer comes back as
+ * `{ ok: false, reason }`; a domain with no binding as `{ ok: true, wallets: [] }`.
+ */
+export declare function resolveDomainBinding(domain: string, opts?: DomainProofOptions): Promise<DomainBindingResult>;
+/** The outcome of checking a domain against an expected wallet. */
+export interface VerifyDomainBindingResult {
+    /** True iff the domain's `_x1id` TXT binds `expectedWallet` and the lookup
+     *  succeeded. */
+    readonly ok: boolean;
+    /** Every wallet the domain binds (base58, canonical) — for context/UX even on
+     *  a mismatch. Empty on a lookup failure. */
+    readonly found: string[];
+    /** Why `ok` is false: `"invalid-domain"` / `"invalid-wallet"` for bad inputs,
+     *  a DoH failure reason (`"timeout"`, `"network-error"`, ...), `"not-found"`
+     *  when the domain publishes no binding, or `"mismatch"` when it binds other
+     *  wallets but not the expected one. Absent when `ok` is true. */
+    readonly reason?: string;
+}
+/**
+ * The core "anyone can check it" primitive: does `<domain>` independently bind
+ * `expectedWallet` in DNS? Returns `{ ok, found, reason? }` and never throws.
+ *
+ * A verifier calling this trusts DNS and the domain owner — NOT x1id's attestor.
+ */
+export declare function verifyDomainBinding(domain: string, expectedWallet: string, opts?: DomainProofOptions): Promise<VerifyDomainBindingResult>;
+/** The combined on-chain-attestation + live-DNS check. */
+export interface VerifyDomainAttestationResult {
+    /** Both halves hold: x1id attested the domain (a non-stale `dns` attestation)
+     *  AND DNS still independently confirms the binding. This is the strongest
+     *  signal this SDK can give for a domain today. */
+    readonly ok: boolean;
+    /** The handle holds a NON-STALE `dns`-kind attestation for the current owner
+     *  ("x1id attested it"). */
+    readonly attested: boolean;
+    /** DNS independently confirms the binding right now ("still current, attestor
+     *  couldn't have lied"). */
+    readonly dnsConfirmed: boolean;
+    /** The wallet(s) the domain currently binds in DNS. */
+    readonly found: string[];
+    /** A note when `ok` is false — e.g. `"attestation-error"` if the chain read
+     *  threw, or the {@link verifyDomainBinding} reason for the DNS half. */
+    readonly reason?: string;
+}
+/**
+ * Convenience: confirm BOTH that x1id attested a domain AND that DNS still
+ * independently backs it up — so a caller learns not just "x1id says so" but
+ * "and it's verifiably still true", closing the attestor's ability to have lied.
+ *
+ * `registeredAt` / `recordsClearedAt` are the owning Handle's fields the caller
+ * already decoded (see {@link import("./accounts.js").parseHandleAccount}); they
+ * are MANDATORY here for the same reason every attestation read demands them —
+ * the staleness rule (`attested_at >= registered_at`, and `>= records_cleared_at`)
+ * decides whether an attestation vouches for the *current* owner at all. The
+ * two halves are evaluated independently, so a caller can see which one holds:
+ * a chain-read failure does not suppress the DNS answer, and vice-versa.
+ *
+ * Never throws: a failed chain read degrades to `attested: false` with
+ * `reason: "attestation-error"`, mirroring `signin.ts`'s best-effort summary.
+ */
+export declare function verifyDomainAttestation(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, domain: string, expectedWallet: string, opts?: DomainProofOptions): Promise<VerifyDomainAttestationResult>;
+export {};

package/dist/domainProof.js

@@ -0,0 +1,278 @@
+/**
+ * Independent, re-verifiable domain->wallet proof via DNS-over-HTTPS (#8318,
+ * Approach C — the "auditable attestor" honesty upgrade).
+ *
+ * # Why this exists
+ *
+ * A `dns`-kind {@link import("./attestation.js").HandleAttestation} records only
+ * that x1id's admin-rotatable attestor key *signed off* on an off-chain DNS
+ * lookup ("attestation.ts" says this plainly): the chain stores the attestor's
+ * say-so, not a proof. The fully-trustless answers (an on-chain DNSSEC verifier,
+ * or a zkTLS proof — Approaches A/B in `docs/trustless-domain-proof-plan.md`)
+ * are BLOCKED on this X1 fork because the runtime does not have the crypto
+ * primitives they need active (`big_mod_exp` / `secp256r1` / `alt_bn128` are all
+ * feature-gated off). Until one of those lands, this module is the shippable
+ * middle ground: it lets ANYONE independently re-resolve the domain's DNS record
+ * and confirm the binding, so the attestor can no longer lie *undetected*. Trust
+ * moves from "the x1id attestor" to "DNS + the domain owner" — a real, cheap
+ * upgrade that needs no on-chain change.
+ *
+ * It is dependency-free and runs in both the browser and Node: a DoH query is a
+ * plain HTTPS GET, and the JSON shape ("application/dns-json", the Cloudflare /
+ * Google convention) is parsed by hand, like the rest of this package.
+ *
+ * # The TXT record convention (the interoperability contract)
+ *
+ * A domain owner proves control of `<domain>` by publishing a TXT record at the
+ * name **`_x1id.<domain>`** whose value is:
+ *
+ *     x1id-wallet=<base58 wallet pubkey>
+ *
+ * - The prefix is the exported {@link TXT_BINDING_PREFIX} (`x1id-wallet=`).
+ * - `<base58 wallet pubkey>` is the 32-byte X1/SVM wallet address, base58, that
+ *   the domain is bound to (the handle's authority wallet). Multiple TXT records
+ *   under the same name are allowed — a domain may bind more than one wallet
+ *   (e.g. during a key rotation); {@link resolveDomainBinding} returns them all.
+ * - A single TXT record split into several character-strings (RFC 1035 §3.3.14 /
+ *   RFC 7208 §3.3) is concatenated with no separator before the prefix is
+ *   matched, exactly as a mail SPF/DKIM verifier would.
+ *
+ * This is the contract a domain owner follows, so it is deliberately simple and
+ * stable. It mirrors the `_dnslink`/`_atproto`/`_domainkey` underscore-prefixed
+ * convention rather than putting x1id data on the apex TXT (which would collide
+ * with SPF/verification tokens from every other service).
+ *
+ * # NOTE — the paired attestor-side follow-up (NOT done here)
+ *
+ * This SDK-only change gives verifiers the re-check primitive. The *other* half
+ * of Approach C — having the attestor publish the exact `_x1id.<domain>` TXT it
+ * checked inside the attestation's `evidence_hash` preimage bundle, so a
+ * back-dated attestation whose TXT was later removed is still disprovable — is a
+ * change to the admin-api attest tooling (`tools/`), tracked as a FOLLOW-UP. See
+ * `docs/trustless-domain-proof-plan.md` §4. Until that ships,
+ * {@link verifyDomainBinding} can only confirm a binding that is *still live* in
+ * DNS; it cannot audit a removed one.
+ */
+import { decodeBase58_32, encodeBase58 } from "./base58.js";
+import { fetchAttestations } from "./attestation.js";
+import { attestationsPassGate, GateKind } from "./gate.js";
+/** The canonical prefix of the `_x1id.<domain>` TXT binding value. A TXT string
+ *  that (after character-string concatenation) starts with this, followed by a
+ *  valid base58 32-byte address, is an x1id binding record. */
+export const TXT_BINDING_PREFIX = "x1id-wallet=";
+/** The DNS label prefixed to a domain to locate its x1id binding TXT records —
+ *  the query name is `${TXT_NAME_PREFIX}.<domain>`. */
+export const TXT_NAME_PREFIX = "_x1id";
+/** DoH JSON `type` code for a TXT record (RFC 1035). */
+const DNS_TYPE_TXT = 16;
+/** Built-in DoH endpoints (both speak the `application/dns-json` shape). */
+const DOH_PROVIDERS = Object.freeze({
+    cloudflare: "https://cloudflare-dns.com/dns-query",
+    google: "https://dns.google/resolve",
+});
+const DEFAULT_TIMEOUT_MS = 6000;
+/** A domain is a case-insensitive dotted hostname (1..253 chars, labels 1..63 of
+ *  `[a-z0-9-]`, no leading/trailing hyphen). Strict enough that the name can be
+ *  safely interpolated into a query and can never smuggle a second query param. */
+const DOMAIN_RE = /^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+function normalizeDomain(domain) {
+    if (typeof domain !== "string")
+        return null;
+    // Tolerate a trailing dot (fully-qualified form) and case; reject everything
+    // else so the name is safe to interpolate into the query.
+    const d = domain.trim().replace(/\.$/, "").toLowerCase();
+    if (!DOMAIN_RE.test(d))
+        return null;
+    return d;
+}
+function buildDohUrl(base, name) {
+    const q = `name=${encodeURIComponent(name)}&type=TXT`;
+    return base.includes("?") ? `${base}&${q}` : `${base}?${q}`;
+}
+/**
+ * Concatenate a DoH TXT `data` field into its logical string.
+ *
+ * DoH returns a TXT record's RDATA as its character-strings, each wrapped in
+ * double quotes; a record split into several character-strings comes back as
+ * several quoted runs (e.g. `"\"x1id-ver\" \"ification=...\""`). Per RFC 1035
+ * §3.3.14 they concatenate with NO separator. Escaped `\"` and `\\` inside a
+ * run are unescaped. A `data` with no quotes at all (some resolvers) is used
+ * verbatim.
+ */
+function unquoteTxtData(data) {
+    if (!data.includes('"'))
+        return data;
+    let out = "";
+    let inStr = false;
+    for (let i = 0; i < data.length; i++) {
+        const c = data[i];
+        if (!inStr) {
+            if (c === '"')
+                inStr = true;
+            // characters between quoted runs (whitespace) are dropped
+            continue;
+        }
+        if (c === "\\") {
+            // escaped char: take the next byte literally
+            const next = data[i + 1];
+            if (next !== undefined) {
+                out += next;
+                i++;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inStr = false;
+            continue;
+        }
+        out += c;
+    }
+    return out;
+}
+/** Extract a canonical base58 wallet from one concatenated TXT string, or null
+ *  if it is not a well-formed x1id binding. */
+function walletFromTxt(txt) {
+    if (!txt.startsWith(TXT_BINDING_PREFIX))
+        return null;
+    const raw = txt.slice(TXT_BINDING_PREFIX.length).trim();
+    const bytes = decodeBase58_32(raw);
+    if (!bytes)
+        return null;
+    // Re-encode so a non-canonical base58 spelling and the caller's wallet compare
+    // byte-for-byte, exactly like the rest of the SDK does.
+    return encodeBase58(bytes);
+}
+async function fetchDohJson(url, fetchImpl, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            signal: controller.signal,
+            // Cloudflare's /dns-query REQUIRES this to return JSON; harmless for Google.
+            headers: { accept: "application/dns-json" },
+        });
+        if (!res.ok)
+            return { ok: false, reason: `doh-http-${res.status}` };
+        const json = (await res.json());
+        return { ok: true, json };
+    }
+    catch (e) {
+        const reason = e?.name === "AbortError" ? "timeout" : "network-error";
+        return { ok: false, reason };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Resolve the wallet(s) a domain binds via its `_x1id.<domain>` TXT records,
+ * independently of x1id's attestor — a DoH GET, parsed and validated defensively.
+ *
+ * Never throws: a network failure, timeout, or malformed answer comes back as
+ * `{ ok: false, reason }`; a domain with no binding as `{ ok: true, wallets: [] }`.
+ */
+export async function resolveDomainBinding(domain, opts) {
+    const canonical = normalizeDomain(domain);
+    if (canonical === null) {
+        return { ok: false, domain: String(domain), wallets: [], reason: "invalid-domain" };
+    }
+    const fetchImpl = opts?.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+        return { ok: false, domain: canonical, wallets: [], reason: "no-fetch" };
+    }
+    const base = opts?.dohUrl ?? DOH_PROVIDERS[opts?.provider ?? "cloudflare"];
+    const url = buildDohUrl(base, `${TXT_NAME_PREFIX}.${canonical}`);
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const res = await fetchDohJson(url, fetchImpl, timeoutMs);
+    if (!res.ok)
+        return { ok: false, domain: canonical, wallets: [], reason: res.reason };
+    const body = res.json;
+    if (typeof body !== "object" || body === null) {
+        return { ok: false, domain: canonical, wallets: [], reason: "malformed-response" };
+    }
+    const b = body;
+    const status = typeof b.Status === "number" ? b.Status : -1;
+    // 0 = NOERROR (parse answers), 3 = NXDOMAIN (the name simply doesn't exist =
+    // no binding, a clean empty result). Anything else (SERVFAIL, etc.) is an
+    // unknown answer, not a proven absence.
+    if (status === 3)
+        return { ok: true, domain: canonical, wallets: [] };
+    if (status !== 0)
+        return { ok: false, domain: canonical, wallets: [], reason: `doh-status-${status}` };
+    const answers = Array.isArray(b.Answer) ? b.Answer : [];
+    const wallets = [];
+    for (const ans of answers) {
+        if (typeof ans !== "object" || ans === null)
+            continue;
+        const a = ans;
+        if (a.type !== DNS_TYPE_TXT)
+            continue; // skip CNAME/other chained answers
+        if (typeof a.data !== "string")
+            continue;
+        const wallet = walletFromTxt(unquoteTxtData(a.data));
+        if (wallet && !wallets.includes(wallet))
+            wallets.push(wallet);
+    }
+    return { ok: true, domain: canonical, wallets };
+}
+/**
+ * The core "anyone can check it" primitive: does `<domain>` independently bind
+ * `expectedWallet` in DNS? Returns `{ ok, found, reason? }` and never throws.
+ *
+ * A verifier calling this trusts DNS and the domain owner — NOT x1id's attestor.
+ */
+export async function verifyDomainBinding(domain, expectedWallet, opts) {
+    const wanted = typeof expectedWallet === "string" ? decodeBase58_32(expectedWallet) : null;
+    if (!wanted)
+        return { ok: false, found: [], reason: "invalid-wallet" };
+    const wantedBase58 = encodeBase58(wanted);
+    const res = await resolveDomainBinding(domain, opts);
+    if (!res.ok)
+        return { ok: false, found: [], reason: res.reason ?? "lookup-failed" };
+    if (res.wallets.length === 0)
+        return { ok: false, found: [], reason: "not-found" };
+    if (!res.wallets.includes(wantedBase58)) {
+        return { ok: false, found: res.wallets, reason: "mismatch" };
+    }
+    return { ok: true, found: res.wallets };
+}
+/**
+ * Convenience: confirm BOTH that x1id attested a domain AND that DNS still
+ * independently backs it up — so a caller learns not just "x1id says so" but
+ * "and it's verifiably still true", closing the attestor's ability to have lied.
+ *
+ * `registeredAt` / `recordsClearedAt` are the owning Handle's fields the caller
+ * already decoded (see {@link import("./accounts.js").parseHandleAccount}); they
+ * are MANDATORY here for the same reason every attestation read demands them —
+ * the staleness rule (`attested_at >= registered_at`, and `>= records_cleared_at`)
+ * decides whether an attestation vouches for the *current* owner at all. The
+ * two halves are evaluated independently, so a caller can see which one holds:
+ * a chain-read failure does not suppress the DNS answer, and vice-versa.
+ *
+ * Never throws: a failed chain read degrades to `attested: false` with
+ * `reason: "attestation-error"`, mirroring `signin.ts`'s best-effort summary.
+ */
+export async function verifyDomainAttestation(rpc, programId, handleAccount, registeredAt, recordsClearedAt, domain, expectedWallet, opts) {
+    // Half 1 (on-chain): a non-stale dns attestation for the current owner. A
+    // read failure must not sink the DNS half — degrade, never throw.
+    let attested = false;
+    let attestationReason;
+    try {
+        const attestations = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt);
+        attested = attestationsPassGate(attestations, { kind: GateKind.dns });
+    }
+    catch {
+        attestationReason = "attestation-error";
+    }
+    // Half 2 (off-chain, independent): DNS still binds the expected wallet.
+    const dns = await verifyDomainBinding(domain, expectedWallet, opts);
+    const ok = attested && dns.ok;
+    const reason = ok ? undefined : (attestationReason ?? (attested ? dns.reason : "not-attested"));
+    return {
+        ok,
+        attested,
+        dnsConfirmed: dns.ok,
+        found: dns.found,
+        ...(reason !== undefined ? { reason } : {}),
+    };
+}

package/dist/index.d.ts

@@ -41,6 +41,7 @@ export * from "./integrator.js";
 export * from "./voucher.js";
 export * from "./agent.js";
 export * from "./register.js";
+export * from "./lease.js";
 export * from "./accounts.js";
 export * from "./x402.js";
 export * from "./recordWrite.js";
@@ -48,6 +49,7 @@ export * from "./clearRecords.js";
 export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
+export * from "./domainProof.js";
 import { type Chain, type Resolved } from "./types.js";
 import { WasmResolver } from "./wasm.js";
 import { type HandleRecord } from "./records.js";

package/dist/index.js

@@ -41,6 +41,7 @@ export * from "./integrator.js";
 export * from "./voucher.js";
 export * from "./agent.js";
 export * from "./register.js";
+export * from "./lease.js";
 // Was previously imported here for internal use only, never re-exported —
 // promoted to public API 2026-09-22 because a second real package (mcp/)
 // now needs `parseHandleAccount`/`RpcFn` directly rather than duplicating
@@ -55,6 +56,7 @@ export * from "./clearRecords.js";
 export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
+export * from "./domainProof.js";
 import { ResolveError, CHAIN_COIN_TYPE } from "./types.js";
 import { parseName } from "./parse.js";
 import { encodeBase58, decodeBase58_32 } from "./base58.js";

package/dist/lease.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Lease-to-own instructions (#8150, #8320) — the SIBLING of `register` for term
+ * leases, not a replacement: the permanent one-time `register` path
+ * (register.ts) is untouched and stays the default.
+ *
+ * - `register_leased` — claim an unregistered `["handle", name]` under a lease,
+ *   paying the first installment now.
+ * - `renew_lease` — pay more toward a leased handle. PERMISSIONLESS: the payer
+ *   need not be the owner (anyone may keep or pay off someone else's lease,
+ *   ENS-registrar-style).
+ * - `reclaim_expired_lease` — take over a leased handle whose grace period has
+ *   ENDED, under a FRESH lease; the reclaimer becomes `owner`. Also
+ *   permissionless. The program enforces `now >= expires_at + grace`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. PDAs are NOT derived here (see delegate.ts) — derive
+ * `["config"]` / `["handle", name]` with your runtime's `findProgramAddress`,
+ * and read `Config.treasury` with {@link fetchConfigTreasury} (register.ts).
+ *
+ * `payment` is in lamports — the amount accepted toward the lease now. The
+ * on-chain `lease_seconds_purchased` / `lease_accept_payment` logic converts it
+ * to lease-time, capped at the permanent price (offering the full permanent
+ * price up front settles the handle permanently in one instruction, writing
+ * `expires_at = 0`). This builder does not compute that split; simulate or
+ * mirror it client-side if you need to preview before signing.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { HandleTypeValue } from "./voucher.js";
+/** `sha256("global:register_leased")[0..8]`. */
+export declare const REGISTER_LEASED_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:renew_lease")[0..8]`. */
+export declare const RENEW_LEASE_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:reclaim_expired_lease")[0..8]`. */
+export declare const RECLAIM_EXPIRED_LEASE_DISCRIMINATOR: Uint8Array;
+export interface RegisterLeasedParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the first lease installment + the `Handle` account's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The handle's owner. Need not sign — may be registered on another's behalf. */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — read it fresh via {@link fetchConfigTreasury}. */
+    readonly treasury: AddressLike;
+    /** The `["handle", name]` PDA being claimed — must not already exist. */
+    readonly handle: AddressLike;
+    /** Canonical form (`parseName(...).canonical`), 1..=32 bytes. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** First lease payment, in lamports. `>= permanentPrice` settles it outright. */
+    readonly payment: bigint;
+}
+/** Build `register_leased`. Data: `disc ‖ borsh(name) ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export declare function buildRegisterLeasedIx(p: RegisterLeasedParams): BuiltInstruction;
+export interface RenewLeaseParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays toward the lease. Signer. PERMISSIONLESS — need NOT be the owner. */
+    readonly payer: AddressLike;
+    /** The `["config"]` PDA (read-only on this path). */
+    readonly config: AddressLike;
+    /** `Config.treasury` — the program address-constrains it to this, so it can't
+     *  be substituted; read it fresh via {@link fetchConfigTreasury}. */
+    readonly treasury: AddressLike;
+    /** The leased `["handle", name]` PDA being paid toward. */
+    readonly handle: AddressLike;
+    /** Lamports to accept toward the lease (capped at the permanent price on-chain). */
+    readonly payment: bigint;
+}
+/** Build `renew_lease`. Data: `disc ‖ payment(u64 LE)`. */
+export declare function buildRenewLeaseIx(p: RenewLeaseParams): BuiltInstruction;
+export interface ReclaimExpiredLeaseParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** Pays the fresh lease's first installment; becomes the new owner. Signer.
+     *  PERMISSIONLESS — anyone may reclaim a grace-ended leased handle. */
+    readonly payer: AddressLike;
+    /** The new owner (typically the same as `payer`). Need not sign. */
+    readonly owner: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** `Config.treasury` — address-constrained on-chain; {@link fetchConfigTreasury}. */
+    readonly treasury: AddressLike;
+    /** The leased `["handle", name]` PDA being reclaimed — its grace must have ended. */
+    readonly handle: AddressLike;
+    readonly handleType: HandleTypeValue;
+    /** The fresh lease's first payment, in lamports. */
+    readonly payment: bigint;
+}
+/** Build `reclaim_expired_lease`. Data: `disc ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export declare function buildReclaimExpiredLeaseIx(p: ReclaimExpiredLeaseParams): BuiltInstruction;

package/dist/lease.js

@@ -0,0 +1,117 @@
+/**
+ * Lease-to-own instructions (#8150, #8320) — the SIBLING of `register` for term
+ * leases, not a replacement: the permanent one-time `register` path
+ * (register.ts) is untouched and stays the default.
+ *
+ * - `register_leased` — claim an unregistered `["handle", name]` under a lease,
+ *   paying the first installment now.
+ * - `renew_lease` — pay more toward a leased handle. PERMISSIONLESS: the payer
+ *   need not be the owner (anyone may keep or pay off someone else's lease,
+ *   ENS-registrar-style).
+ * - `reclaim_expired_lease` — take over a leased handle whose grace period has
+ *   ENDED, under a FRESH lease; the reclaimer becomes `owner`. Also
+ *   permissionless. The program enforces `now >= expires_at + grace`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. PDAs are NOT derived here (see delegate.ts) — derive
+ * `["config"]` / `["handle", name]` with your runtime's `findProgramAddress`,
+ * and read `Config.treasury` with {@link fetchConfigTreasury} (register.ts).
+ *
+ * `payment` is in lamports — the amount accepted toward the lease now. The
+ * on-chain `lease_seconds_purchased` / `lease_accept_payment` logic converts it
+ * to lease-time, capped at the permanent price (offering the full permanent
+ * price up front settles the handle permanently in one instruction, writing
+ * `expires_at = 0`). This builder does not compute that split; simulate or
+ * mirror it client-side if you need to preview before signing.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** `sha256("global:register_leased")[0..8]`. */
+export const REGISTER_LEASED_DISCRIMINATOR = Uint8Array.from([83, 192, 142, 193, 191, 53, 8, 15]);
+/** `sha256("global:renew_lease")[0..8]`. */
+export const RENEW_LEASE_DISCRIMINATOR = Uint8Array.from([11, 121, 141, 53, 216, 217, 123, 139]);
+/** `sha256("global:reclaim_expired_lease")[0..8]`. */
+export const RECLAIM_EXPIRED_LEASE_DISCRIMINATOR = Uint8Array.from([66, 80, 245, 8, 1, 21, 161, 110]);
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+function assertHandleType(t) {
+    if (!Number.isInteger(t) || t < 0 || t > 3) {
+        throw new Error("handleType must be 0 (Human), 1 (Merchant), 2 (Org) or 3 (Agent)");
+    }
+}
+function encodeName(name) {
+    const b = new TextEncoder().encode(name);
+    if (b.length < 1 || b.length > 32)
+        throw new Error("name must be 1..=32 bytes (UTF-8)");
+    return b;
+}
+function u64le(n) {
+    if (n < 0n)
+        throw new Error("payment must be a non-negative u64 (lamports)");
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, n, true);
+    return b;
+}
+/** Build `register_leased`. Data: `disc ‖ borsh(name) ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export function buildRegisterLeasedIx(p) {
+    assertHandleType(p.handleType);
+    const nb = encodeName(p.name);
+    const data = new Uint8Array(8 + 4 + nb.length + 1 + 8);
+    data.set(REGISTER_LEASED_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint32(8, nb.length, true);
+    data.set(nb, 12);
+    data[12 + nb.length] = p.handleType;
+    data.set(u64le(p.payment), 12 + nb.length + 1);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `renew_lease`. Data: `disc ‖ payment(u64 LE)`. */
+export function buildRenewLeaseIx(p) {
+    const data = new Uint8Array(8 + 8);
+    data.set(RENEW_LEASE_DISCRIMINATOR, 0);
+    data.set(u64le(p.payment), 8);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.treasury, "treasury"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `reclaim_expired_lease`. Data: `disc ‖ handleType(u8) ‖ payment(u64 LE)`. */
+export function buildReclaimExpiredLeaseIx(p) {
+    assertHandleType(p.handleType);
+    const data = new Uint8Array(8 + 1 + 8);
+    data.set(RECLAIM_EXPIRED_LEASE_DISCRIMINATOR, 0);
+    data[8] = p.handleType;
+    data.set(u64le(p.payment), 9);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/dist/voucher.d.ts

@@ -128,3 +128,56 @@ export interface RefundVoucherParams {
 }
 /** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
 export declare function buildRefundVoucherIx(p: RefundVoucherParams): BuiltInstruction;
+/** `sha256("global:claim_voucher_tokenized")[0..8]`. */
+export declare const CLAIM_VOUCHER_TOKENIZED_DISCRIMINATOR: Uint8Array;
+export interface ClaimVoucherTokenizedParams {
+    readonly programId: AddressLike;
+    /** Submits + signs; fronts the tx fee (reimbursed) + the handle rent. */
+    readonly claimer: AddressLike;
+    readonly config: AddressLike;
+    readonly treasury: AddressLike;
+    readonly voucher: AddressLike;
+    /** The original voucher payer — receives rent back when the voucher closes. */
+    readonly voucherPayer: AddressLike;
+    /** Who the pNFT + ownership go to: the bound recipient, or the claimer for an
+     *  open voucher. The mint's ATA + token record derive against THIS address. */
+    readonly owner: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    readonly name: string;
+    /** `["nft_mint", handle]` PDA. */
+    readonly mint: AddressLike;
+    /** `owner`'s associated token account for `mint` (receives the frozen unit). */
+    readonly ownerTokenAccount: AddressLike;
+    /** Metaplex metadata PDA for `mint`. */
+    readonly metadata: AddressLike;
+    /** Metaplex master-edition PDA for `mint`. */
+    readonly masterEdition: AddressLike;
+    /** pNFT TokenRecord PDA for (`mint`, `ownerTokenAccount`). */
+    readonly tokenRecord: AddressLike;
+    /** The collection parent mint (`["collection_mint"]`). */
+    readonly collectionMint: AddressLike;
+    /** The collection parent metadata (writable — sized-collection bump). */
+    readonly collectionMetadata: AddressLike;
+    /** The collection parent master edition. */
+    readonly collectionMasterEdition: AddressLike;
+    /** The collection authority PDA. */
+    readonly collectionAuthority: AddressLike;
+    /** The integrator wallet — REQUIRED iff the voucher carries one; must equal
+     *  the voucher's `integrator`. Omit otherwise. */
+    readonly integrator?: AddressLike;
+}
+/**
+ * Build `claim_voucher_tokenized` (#8335) — the tokenized sibling of
+ * {@link buildClaimVoucherIx} and the DEFAULT path the live gift-claim flow
+ * uses: it registers the handle AND mints its tradeable capability pNFT in one
+ * instruction. The pNFT + ownership go to `owner` (the bound recipient, or the
+ * claimer for an open voucher), so `ownerTokenAccount` / `tokenRecord` derive
+ * against `owner`, not the claimer. Data: `disc ‖ borsh(name)` — the handle type
+ * comes from the voucher, not an argument.
+ *
+ * The register + 3 Metaplex CPIs exceed the 200k default compute budget —
+ * prepend a ComputeBudget `setComputeUnitLimit` instruction in the SAME
+ * transaction (the app uses ~400k) or the claim fails on-chain.
+ */
+export declare function buildClaimVoucherTokenizedIx(p: ClaimVoucherTokenizedParams): BuiltInstruction;

package/dist/voucher.js

@@ -183,3 +183,59 @@ export function buildRefundVoucherIx(p) {
         data,
     };
 }
+// ===================== claim_voucher_tokenized (gift NFTs, #8335) =====================
+/** `sha256("global:claim_voucher_tokenized")[0..8]`. */
+export const CLAIM_VOUCHER_TOKENIZED_DISCRIMINATOR = Uint8Array.from([131, 111, 174, 105, 154, 248, 191, 235]);
+// Fixed Metaplex / SPL program ids + sysvar in the pNFT-mint tail — hardcoded,
+// never derived (matches the app's mintNft.ts).
+const TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+const ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+const TOKEN_METADATA_PROGRAM = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s";
+const SYSVAR_INSTRUCTIONS = "Sysvar1nstructions1111111111111111111111111";
+/**
+ * Build `claim_voucher_tokenized` (#8335) — the tokenized sibling of
+ * {@link buildClaimVoucherIx} and the DEFAULT path the live gift-claim flow
+ * uses: it registers the handle AND mints its tradeable capability pNFT in one
+ * instruction. The pNFT + ownership go to `owner` (the bound recipient, or the
+ * claimer for an open voucher), so `ownerTokenAccount` / `tokenRecord` derive
+ * against `owner`, not the claimer. Data: `disc ‖ borsh(name)` — the handle type
+ * comes from the voucher, not an argument.
+ *
+ * The register + 3 Metaplex CPIs exceed the 200k default compute budget —
+ * prepend a ComputeBudget `setComputeUnitLimit` instruction in the SAME
+ * transaction (the app uses ~400k) or the claim fails on-chain.
+ */
+export function buildClaimVoucherTokenizedIx(p) {
+    const name = encString(p.name);
+    const data = new Uint8Array(8 + name.length);
+    data.set(CLAIM_VOUCHER_TOKENIZED_DISCRIMINATOR, 0);
+    data.set(name, 8);
+    const keys = [
+        { pubkey: toBase58(p.claimer, "claimer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.treasury, "treasury"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.voucherPayer, "voucherPayer"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        // Metaplex pNFT tail — order + flags verbatim from mintNft.ts::tokenizedTailKeys.
+        { pubkey: toBase58(p.mint, "mint"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.ownerTokenAccount, "ownerTokenAccount"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.metadata, "metadata"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.masterEdition, "masterEdition"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.tokenRecord, "tokenRecord"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.collectionMint, "collectionMint"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.collectionMetadata, "collectionMetadata"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.collectionMasterEdition, "collectionMasterEdition"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.collectionAuthority, "collectionAuthority"), isSigner: false, isWritable: false },
+        { pubkey: TOKEN_METADATA_PROGRAM, isSigner: false, isWritable: false },
+        { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        { pubkey: ASSOCIATED_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+        { pubkey: SYSVAR_INSTRUCTIONS, isSigner: false, isWritable: false },
+    ];
+    if (p.integrator !== undefined) {
+        keys.push({ pubkey: toBase58(p.integrator, "integrator"), isSigner: false, isWritable: true });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}

package/package.json

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