@x1id/resolve 0.23.0 → 0.43.0

package/dist/gate.d.ts

@@ -13,17 +13,50 @@
  * {@link markHolderMismatch} onto the fetched set never admits an inherited
  * badge. Nothing here trusts an off-chain claim: every input is an on-chain,
  * attestor-signed `Attestation` account.
+ *
+ * # Third-party credentials (upgrade 6, docs/specs/x1id-credentials.md)
+ *
+ * A gate may also require an issuer-signed credential:
+ * `{ credential: { schema, issuers, minRemainingSecs? } }`, combined with
+ * `{ allOf: Gate[] }` / `{ anyOf: Gate[] }`. `issuers` is an explicit, non-empty
+ * list of Issuer PDAs, or the alias `"x1id-recommended"` (X1ID's ADVISORY
+ * list, which an app must choose; {@link resolveRecommendedIssuers} snapshots
+ * it into a fixed list). `"any-verified"`, `{ kind }` and `{ anyOf: kinds }`
+ * keep reading ONLY attestations: a credential never satisfies the blue tick.
  */
 import { type HandleAttestation } from "./attestation.js";
 import type { RpcFn } from "./accounts.js";
+import type { PdaFinder } from "./namespacePricing.js";
+import { type HandleCredential } from "./credentials.js";
+/** The alias for X1ID's advisory recommended-issuer list. */
+export declare const RECOMMENDED_ISSUERS_ALIAS = "x1id-recommended";
+/** Opt-in to follow the live list instead of a snapshot (dev-api policies). */
+export declare const RECOMMENDED_ISSUERS_LIVE_ALIAS = "x1id-recommended:live";
+/** A third-party credential requirement. */
+export interface CredentialClause {
+    /** The issuer-defined schema id (u32). */
+    readonly schema: number;
+    /** Issuer PDAs (base58, 1-32), or the advisory-list alias. */
+    readonly issuers: readonly string[] | typeof RECOMMENDED_ISSUERS_ALIAS | typeof RECOMMENDED_ISSUERS_LIVE_ALIAS;
+    /** Demand at least this much validity left (seconds, >= 0). */
+    readonly minRemainingSecs?: number;
+}
 /** What a handle must prove to pass the gate:
  *  - `"any-verified"` — at least one non-stale attestation of any kind.
  *  - `{ kind }` — a non-stale attestation of exactly that kind.
- *  - `{ anyOf }` — a non-stale attestation of any listed kind (e.g. X OR GitHub). */
+ *  - `{ anyOf: kinds }` — a non-stale attestation of any listed kind (e.g. X OR GitHub).
+ *  - `{ credential }` — a valid third-party credential (see {@link CredentialClause}).
+ *  - `{ allOf: Gate[] }` / `{ anyOf: Gate[] }` — every / any sub-gate. */
 export type Gate = "any-verified" | {
     readonly kind: number;
 } | {
     readonly anyOf: readonly number[];
+} | {
+    readonly credential: CredentialClause;
+} | {
+    readonly allOf: readonly Gate[];
+} | {
+    readonly anyOf: readonly Gate[];
 };
 /** Named platform kinds, re-exported so callers gate without magic numbers. */
 export declare const GateKind: {
@@ -34,17 +67,74 @@ export declare const GateKind: {
     readonly github: 4;
     readonly telegram: 5;
 };
+/**
+ * Validate a gate's shape (throws a typed `ResolveError("invalid-input")`).
+ * Credential clauses need a u32 `schema`, a non-negative integer
+ * `minRemainingSecs`, and `issuers` that is the alias or 1-32 distinct
+ * base58 addresses. Nesting is bounded (depth 4, 16 clauses).
+ */
+export declare function validateGate(gate: Gate): void;
+/** Every credential clause in `gate` (depth-first). */
+export declare function credentialClauses(gate: Gate): CredentialClause[];
+/**
+ * Replace the `"x1id-recommended"` alias with a fixed copy of `list` (a
+ * snapshot): a later change of the advisory list, or a compromised admin key
+ * adding an issuer, then cannot change this gate silently. The
+ * `"x1id-recommended:live"` alias is kept unless `resolveLive` is set.
+ * Throws if the list is empty (a gate must name at least one issuer).
+ */
+export declare function resolveRecommendedIssuers(gate: Gate, list: readonly string[], opts?: {
+    readonly resolveLive?: boolean;
+}): Gate;
+/** Inputs for evaluating credential clauses. */
+export interface CredentialGateInputs {
+    /** `{ schema, issuers }` → the credentials found (any validity). */
+    readonly credentialsFor: (clause: CredentialClause) => readonly HandleCredential[];
+}
+/** Which clauses passed, for display. */
+export interface GateEvaluation {
+    readonly passed: boolean;
+    /** Human-readable ids of the satisfied leaf clauses (`kind:4`,
+     *  `credential:<issuer>:<schema>`, `any-verified`). */
+    readonly matched: readonly string[];
+}
+/**
+ * Pure evaluation of any gate. Attestation clauses read `attestations` only;
+ * credential clauses read `credentials` (required when the gate has any).
+ * Stale and holder-mismatched attestations never count; a credential counts
+ * only when `validity.valid` (credentials.ts `credentialValidity`).
+ */
+export declare function evaluateGate(gate: Gate, attestations: readonly HandleAttestation[], credentials?: CredentialGateInputs): GateEvaluation;
 /** Pure check: do these (already-fetched) attestations satisfy the gate?
- *  Stale and holder-mismatched (H5) attestations never count. */
+ *  Stale and holder-mismatched (H5) attestations never count. A gate with a
+ *  credential clause throws here: use {@link evaluateGate} with credentials. */
 export declare function attestationsPassGate(attestations: readonly HandleAttestation[], gate: Gate): boolean;
+/** Extra inputs `handlePassesGate` needs for credential clauses. */
+export interface CredentialGateOptions {
+    /** `find_program_address` (see namespacePricing.ts `PdaFinder`). */
+    readonly find: PdaFinder;
+    /** The handle's CURRENT authority: `Handle.owner` while untokenized, the
+     *  pNFT holder once tokenized. */
+    readonly currentHolder: string | null;
+    /** Unix seconds (default: now). */
+    readonly nowSecs?: bigint | number;
+    /** A pre-fetched advisory list for the alias (default: read from chain). */
+    readonly recommendedIssuers?: readonly string[];
+}
 /** Fetch a handle's attestations and test the gate in one call. `handleAccount`,
  *  `registeredAt`, `recordsClearedAt` and `holderEpoch` come from the handle you
  *  resolved (name → `deriveHandleAccount` → decode). `holderEpoch` (H5 / PR
  *  #466, 0 if absent) folds into the staleness epoch so the gate matches the
  *  on-chain rule `attested_at >= max(registered_at, holder_epoch)`; it defaults
  *  to `0n` for backward compatibility. Returns the pass/fail plus the
- *  attestations so a caller can also render WHICH signals matched. */
-export declare function handlePassesGate(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, gate: Gate, holderEpoch?: bigint): Promise<{
+ *  attestations so a caller can also render WHICH signals matched.
+ *
+ *  A gate with credential clauses also needs `credentialOpts` (the PDA
+ *  finder and the current holder); its credentials are read from the chain
+ *  (derived PDAs, one `getMultipleAccounts` per clause) and returned too. */
+export declare function handlePassesGate(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, gate: Gate, holderEpoch?: bigint, credentialOpts?: CredentialGateOptions): Promise<{
     readonly passed: boolean;
     readonly attestations: HandleAttestation[];
+    readonly credentials?: readonly HandleCredential[];
+    readonly matched?: readonly string[];
 }>;

package/dist/gate.js

@@ -13,9 +13,25 @@
  * {@link markHolderMismatch} onto the fetched set never admits an inherited
  * badge. Nothing here trusts an off-chain claim: every input is an on-chain,
  * attestor-signed `Attestation` account.
+ *
+ * # Third-party credentials (upgrade 6, docs/specs/x1id-credentials.md)
+ *
+ * A gate may also require an issuer-signed credential:
+ * `{ credential: { schema, issuers, minRemainingSecs? } }`, combined with
+ * `{ allOf: Gate[] }` / `{ anyOf: Gate[] }`. `issuers` is an explicit, non-empty
+ * list of Issuer PDAs, or the alias `"x1id-recommended"` (X1ID's ADVISORY
+ * list, which an app must choose; {@link resolveRecommendedIssuers} snapshots
+ * it into a fixed list). `"any-verified"`, `{ kind }` and `{ anyOf: kinds }`
+ * keep reading ONLY attestations: a credential never satisfies the blue tick.
  */
 import { fetchAttestations, isHandleVerified, ATTESTATION_KIND_DNS, ATTESTATION_KIND_SOCIAL, ATTESTATION_KIND_X, ATTESTATION_KIND_DISCORD, ATTESTATION_KIND_GITHUB, ATTESTATION_KIND_TELEGRAM, } from "./attestation.js";
 import { ResolveError } from "./types.js";
+import { decodeBase58_32 } from "./base58.js";
+import { fetchHandleCredentials, fetchRecommendedIssuers, MAX_RECOMMENDED_ISSUERS, } from "./credentials.js";
+/** The alias for X1ID's advisory recommended-issuer list. */
+export const RECOMMENDED_ISSUERS_ALIAS = "x1id-recommended";
+/** Opt-in to follow the live list instead of a snapshot (dev-api policies). */
+export const RECOMMENDED_ISSUERS_LIVE_ALIAS = "x1id-recommended:live";
 /** Named platform kinds, re-exported so callers gate without magic numbers. */
 export const GateKind = {
     dns: ATTESTATION_KIND_DNS,
@@ -25,8 +41,166 @@ export const GateKind = {
     github: ATTESTATION_KIND_GITHUB,
     telegram: ATTESTATION_KIND_TELEGRAM,
 };
+const MAX_GATE_DEPTH = 4;
+const MAX_GATE_NODES = 16;
+function bad(msg, detail) {
+    throw new ResolveError("invalid-input", msg, typeof detail === "string" ? detail : JSON.stringify(detail));
+}
+/**
+ * Validate a gate's shape (throws a typed `ResolveError("invalid-input")`).
+ * Credential clauses need a u32 `schema`, a non-negative integer
+ * `minRemainingSecs`, and `issuers` that is the alias or 1-32 distinct
+ * base58 addresses. Nesting is bounded (depth 4, 16 clauses).
+ */
+export function validateGate(gate) {
+    let nodes = 0;
+    const walk = (g, depth) => {
+        if (++nodes > MAX_GATE_NODES)
+            bad("gate has too many clauses (max 16)", g);
+        if (depth > MAX_GATE_DEPTH)
+            bad("gate is nested too deeply (max 4)", g);
+        if (g === "any-verified")
+            return;
+        if (g === null || typeof g !== "object" || Array.isArray(g)) {
+            bad('gate must be "any-verified", { kind }, { anyOf }, { allOf } or { credential }', String(g));
+        }
+        const o = g;
+        if ("kind" in o) {
+            if (typeof o.kind !== "number")
+                bad("kind must be a number", g);
+            return;
+        }
+        if ("anyOf" in o || "allOf" in o) {
+            const list = ("anyOf" in o ? o.anyOf : o.allOf);
+            if (!Array.isArray(list))
+                bad("anyOf / allOf needs an array", g);
+            // `{ anyOf: kinds }` keeps its pre-credentials meaning (an empty list
+            // simply never passes).
+            if ("anyOf" in o && list.every((x) => typeof x === "number"))
+                return;
+            if (list.length === 0)
+                bad("allOf / anyOf of gates needs at least one gate", g);
+            for (const sub of list)
+                walk(sub, depth + 1);
+            return;
+        }
+        if ("credential" in o) {
+            const c = o.credential;
+            if (c === null || typeof c !== "object")
+                bad("credential clause must be an object", g);
+            if (!Number.isInteger(c.schema) || c.schema < 0 || c.schema > 0xffff_ffff)
+                bad("credential.schema must be a u32", g);
+            if (c.minRemainingSecs !== undefined && (!Number.isSafeInteger(c.minRemainingSecs) || c.minRemainingSecs < 0)) {
+                bad("credential.minRemainingSecs must be a non-negative integer", g);
+            }
+            const iss = c.issuers;
+            if (iss === RECOMMENDED_ISSUERS_ALIAS || iss === RECOMMENDED_ISSUERS_LIVE_ALIAS)
+                return;
+            if (!Array.isArray(iss) || iss.length === 0)
+                bad("credential.issuers must be a non-empty list or \"x1id-recommended\"", g);
+            if (iss.length > MAX_RECOMMENDED_ISSUERS)
+                bad("credential.issuers has more than 32 entries", g);
+            if (new Set(iss).size !== iss.length)
+                bad("credential.issuers has duplicates", g);
+            for (const a of iss)
+                if (typeof a !== "string" || !decodeBase58_32(a))
+                    bad("credential.issuers entries must be base58 addresses", a);
+            return;
+        }
+        bad("gate object needs a `kind`, `anyOf`, `allOf` or `credential`", g);
+    };
+    walk(gate, 0);
+}
+/** Every credential clause in `gate` (depth-first). */
+export function credentialClauses(gate) {
+    const out = [];
+    const walk = (g) => {
+        if (g === "any-verified" || typeof g !== "object" || g === null)
+            return;
+        if ("credential" in g)
+            out.push(g.credential);
+        else if ("allOf" in g)
+            g.allOf.forEach(walk);
+        else if ("anyOf" in g && !g.anyOf.every((x) => typeof x === "number"))
+            g.anyOf.forEach(walk);
+    };
+    walk(gate);
+    return out;
+}
+/**
+ * Replace the `"x1id-recommended"` alias with a fixed copy of `list` (a
+ * snapshot): a later change of the advisory list, or a compromised admin key
+ * adding an issuer, then cannot change this gate silently. The
+ * `"x1id-recommended:live"` alias is kept unless `resolveLive` is set.
+ * Throws if the list is empty (a gate must name at least one issuer).
+ */
+export function resolveRecommendedIssuers(gate, list, opts = {}) {
+    const map = (g) => {
+        if (g === "any-verified" || typeof g !== "object" || g === null)
+            return g;
+        if ("credential" in g) {
+            const iss = g.credential.issuers;
+            const alias = iss === RECOMMENDED_ISSUERS_ALIAS || (opts.resolveLive === true && iss === RECOMMENDED_ISSUERS_LIVE_ALIAS);
+            if (!alias)
+                return g;
+            if (list.length === 0)
+                bad("the recommended issuer list is empty", g);
+            return { credential: { ...g.credential, issuers: [...list] } };
+        }
+        if ("allOf" in g)
+            return { allOf: g.allOf.map(map) };
+        if ("anyOf" in g && !g.anyOf.every((x) => typeof x === "number"))
+            return { anyOf: g.anyOf.map(map) };
+        return g;
+    };
+    return map(gate);
+}
+/**
+ * Pure evaluation of any gate. Attestation clauses read `attestations` only;
+ * credential clauses read `credentials` (required when the gate has any).
+ * Stale and holder-mismatched attestations never count; a credential counts
+ * only when `validity.valid` (credentials.ts `credentialValidity`).
+ */
+export function evaluateGate(gate, attestations, credentials) {
+    validateGate(gate);
+    const matched = [];
+    const evalNode = (g) => {
+        if (g === "any-verified") {
+            const ok = isHandleVerified(attestations);
+            if (ok)
+                matched.push("any-verified");
+            return ok;
+        }
+        if ("kind" in g)
+            return kinds([g.kind]);
+        if ("credential" in g) {
+            if (!credentials)
+                bad("a credential gate needs credential inputs (use handlePassesGate with opts, or evaluateGate with credentials)", g);
+            const c = g.credential;
+            if (!Array.isArray(c.issuers))
+                bad("resolve the \"x1id-recommended\" alias first (resolveRecommendedIssuers)", g);
+            const hit = credentials.credentialsFor(c).find((h) => h.validity.valid && c.issuers.includes(h.credential.issuer));
+            if (hit)
+                matched.push(`credential:${hit.credential.issuer}:${c.schema}`);
+            return hit !== undefined;
+        }
+        if ("allOf" in g)
+            return g.allOf.map(evalNode).every(Boolean);
+        if (g.anyOf.every((x) => typeof x === "number"))
+            return kinds(g.anyOf);
+        return g.anyOf.map(evalNode).some(Boolean);
+    };
+    const kinds = (ks) => {
+        const hit = attestations.find((a) => !a.stale && !a.holderMismatch && ks.includes(a.kind));
+        if (hit)
+            matched.push(`kind:${hit.kind}`);
+        return hit !== undefined;
+    };
+    return { passed: evalNode(gate), matched };
+}
 /** Pure check: do these (already-fetched) attestations satisfy the gate?
- *  Stale and holder-mismatched (H5) attestations never count. */
+ *  Stale and holder-mismatched (H5) attestations never count. A gate with a
+ *  credential clause throws here: use {@link evaluateGate} with credentials. */
 export function attestationsPassGate(attestations, gate) {
     if (gate === "any-verified")
         return isHandleVerified(attestations);
@@ -36,11 +210,10 @@ export function attestationsPassGate(attestations, gate) {
     if (gate === null || typeof gate !== "object") {
         throw new ResolveError("invalid-input", 'gate must be "any-verified", { kind } or { anyOf: [...] }', String(gate));
     }
-    const kinds = "kind" in gate ? [gate.kind] : "anyOf" in gate ? gate.anyOf : null;
-    if (kinds === null) {
+    if (!("kind" in gate) && !("anyOf" in gate) && !("allOf" in gate) && !("credential" in gate)) {
         throw new ResolveError("invalid-input", "gate object needs a `kind` or `anyOf`", JSON.stringify(gate));
     }
-    return attestations.some((a) => !a.stale && !a.holderMismatch && kinds.includes(a.kind));
+    return evaluateGate(gate, attestations).passed;
 }
 /** Fetch a handle's attestations and test the gate in one call. `handleAccount`,
  *  `registeredAt`, `recordsClearedAt` and `holderEpoch` come from the handle you
@@ -48,8 +221,34 @@ export function attestationsPassGate(attestations, gate) {
  *  #466, 0 if absent) folds into the staleness epoch so the gate matches the
  *  on-chain rule `attested_at >= max(registered_at, holder_epoch)`; it defaults
  *  to `0n` for backward compatibility. Returns the pass/fail plus the
- *  attestations so a caller can also render WHICH signals matched. */
-export async function handlePassesGate(rpc, programId, handleAccount, registeredAt, recordsClearedAt, gate, holderEpoch = 0n) {
+ *  attestations so a caller can also render WHICH signals matched.
+ *
+ *  A gate with credential clauses also needs `credentialOpts` (the PDA
+ *  finder and the current holder); its credentials are read from the chain
+ *  (derived PDAs, one `getMultipleAccounts` per clause) and returned too. */
+export async function handlePassesGate(rpc, programId, handleAccount, registeredAt, recordsClearedAt, gate, holderEpoch = 0n, credentialOpts) {
+    validateGate(gate);
     const attestations = await fetchAttestations(rpc, programId, handleAccount, registeredAt, recordsClearedAt, holderEpoch);
-    return { passed: attestationsPassGate(attestations, gate), attestations };
+    const clauses = credentialClauses(gate);
+    if (clauses.length === 0)
+        return { passed: attestationsPassGate(attestations, gate), attestations };
+    if (!credentialOpts) {
+        throw new ResolveError("invalid-input", "a credential gate needs credentialOpts { find, currentHolder }", JSON.stringify(gate));
+    }
+    const needsList = clauses.some((c) => !Array.isArray(c.issuers));
+    const list = needsList ? (credentialOpts.recommendedIssuers ?? (await fetchRecommendedIssuers(rpc, credentialOpts.find, programId))) : [];
+    const resolved = needsList ? resolveRecommendedIssuers(gate, list, { resolveLive: true }) : gate;
+    const now = credentialOpts.nowSecs ?? BigInt(Math.floor(Date.now() / 1000));
+    const ctx = {
+        handle: handleAccount,
+        registeredAt,
+        holderEpoch,
+        currentHolder: credentialOpts.currentHolder,
+    };
+    const found = new Map();
+    for (const c of credentialClauses(resolved)) {
+        found.set(c, await fetchHandleCredentials(rpc, credentialOpts.find, programId, ctx, c.schema, c.issuers, now, c.minRemainingSecs ?? 0));
+    }
+    const ev = evaluateGate(resolved, attestations, { credentialsFor: (c) => found.get(c) ?? [] });
+    return { passed: ev.passed, attestations, credentials: [...found.values()].flat(), matched: ev.matched };
 }

package/dist/gateClient.d.ts

@@ -41,6 +41,16 @@ export interface GateAttestationView {
     readonly kind: number;
     readonly attested_at: number;
 }
+/** One third-party credential the decision looked at. */
+export interface GateCredentialView {
+    readonly issuer: string;
+    readonly schema: number;
+    readonly subject: string;
+    readonly issued_at: number;
+    readonly expires_at: number;
+    readonly valid: boolean;
+    readonly invalid_reasons: readonly string[];
+}
 /** The decision the service returned. */
 export interface GateCheckResult {
     readonly passed: boolean;
@@ -50,6 +60,8 @@ export interface GateCheckResult {
     };
     readonly policy: Gate;
     readonly attestations: readonly GateAttestationView[];
+    /** Credentials read for a policy with `{ credential }` clauses (upgrade 6). */
+    readonly credentials?: readonly GateCredentialView[];
     readonly reason?: "no-primary-handle" | "handle-not-registered";
 }
 /** Thrown when the decision could not be obtained (network, auth, 5xx, bad

package/dist/giftLink.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Open gift links (docs/specs/gift-links.md): send XNT or a prepaid `@name` to
+ * whoever opens a link. Instruction builders, the `GiftLink` decoder, the PDA
+ * finder and the client helpers that make / parse the link itself.
+ *
+ * # How it works
+ *
+ * 1. The sender's client generates a fresh EPHEMERAL ed25519 keypair
+ *    ({@link newGiftLinkKey}). Its public key is the `gift_key`; its secret
+ *    goes ONLY into the link's URL fragment ({@link giftLinkUrl}):
+ *    `https://app.x1id.io/gift/link#k=<base58 64-byte secret key>`. A fragment
+ *    is never sent to a server.
+ * 2. `create_gift_link` (sender + gift key sign) escrows the value under
+ *    `["gift", gift_key]` ({@link findGiftLinkPda}).
+ * 3. The recipient opens the link ({@link parseGiftLinkUrl}) and submits
+ *    `claim_gift_link` (XNT) or `claim_gift_link_name` (a name, minted as a
+ *    pNFT) SIGNED BY THE GIFT KEY, naming their own wallet as destination.
+ *    Any wallet may pay the fee (a relayer works). Because the destination is
+ *    part of the gift-key-signed message, nobody who sees the claim in flight
+ *    can redirect it (unlike the removed open vouchers, audit S6).
+ * 4. Unclaimed: the sender may cancel ({@link buildRefundGiftLinkIx}) any time;
+ *    after `expiresAt` anyone may return it to the sender.
+ *
+ * Whoever holds the link can claim the gift: treat it like cash. Never reuse a
+ * gift key (generate one per link).
+ *
+ * Routed through the program's `fallback` (`extra_ix`): `sha256("global:<name>")
+ * [..8]` + raw Borsh, accounts exactly in the order of the program's
+ * `Accounts` structs. Hand-rolled, no web3.js. Key generation uses WebCrypto
+ * Ed25519 (Node 20+, current browsers); pass your own key if unavailable.
+ */
+import type { AddressLike, BuiltInstruction, InstructionKey } from "./delegate.js";
+import type { RpcFn } from "./accounts.js";
+import type { PdaFinder } from "./namespacePricing.js";
+import { type TokenizedTailAccounts } from "./mintNft.js";
+import { type HandleTypeValue } from "./voucher.js";
+/** Seed prefix of the escrow PDA: `["gift", gift_key]`. */
+export declare const GIFT_LINK_SEED = "gift";
+/** Allocated size of a `GiftLink` (8-byte discriminator + `INIT_SPACE`). */
+export declare const GIFT_LINK_ACCOUNT_LEN: number;
+/** Longest a gift link may stay open (same cap as vouchers: 366 days). */
+export declare const MAX_GIFT_LINK_DURATION_SECS: number;
+/** Where the app opens gift links. The secret goes after `#k=`. */
+export declare const GIFT_LINK_BASE_URL = "https://app.x1id.io/gift/link";
+/** A sensible client default for `expiresAt`: 30 days. */
+export declare const DEFAULT_GIFT_LINK_TTL_SECS: number;
+/** Compute-unit limit to request for `claim_gift_link_name` (measured
+ *  ~307k on litesvm with the real Metaplex program; same headroom as
+ *  `REGISTER_TOKENIZED_CU_LIMIT`). */
+export declare const CLAIM_GIFT_LINK_NAME_CU_LIMIT = 420000;
+/** `GiftLink.kind` (Borsh enum index). */
+export declare const GIFT_KIND: {
+    readonly Xnt: 0;
+    readonly Name: 1;
+};
+export type GiftKindName = "xnt" | "name";
+/** `sha256("global:create_gift_link")[..8]`. */
+export declare const CREATE_GIFT_LINK_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:claim_gift_link")[..8]`. */
+export declare const CLAIM_GIFT_LINK_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:claim_gift_link_name")[..8]`. */
+export declare const CLAIM_GIFT_LINK_NAME_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:refund_gift_link")[..8]`. */
+export declare const REFUND_GIFT_LINK_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:GiftLink")[..8]`. */
+export declare const GIFT_LINK_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** Byte offsets inside a raw `GiftLink` (fixed up to `integrator`), for
+ *  `getProgramAccounts` `memcmp` filters (e.g. a sender's open links). */
+export declare const GIFT_LINK_OFFSETS: {
+    readonly version: 8;
+    readonly sender: 9;
+    readonly giftKey: 41;
+    readonly kind: 73;
+    readonly amount: 74;
+    readonly name: 82;
+    readonly nameLen: 114;
+    readonly handleType: 115;
+    readonly integrator: 116;
+};
+/** Program error codes added for gift links (`RegistryError`). Gift links
+ *  also reuse `VoucherNameRegistered` (6057), `BadVoucherExpiry` (6058),
+ *  `PriceBelowRent` (6086), `ProtocolLockedDown` (6102) and
+ *  `VoucherExpiryTooFar` (6112). */
+export declare const GIFT_LINK_ERRORS: {
+    readonly GiftAmountInvalid: 6151;
+    readonly GiftLinkExpired: 6152;
+    readonly GiftLinkWrongKind: 6153;
+    readonly GiftLinkBadDestination: 6154;
+    readonly GiftLinkNotRefundable: 6155;
+    readonly GiftLinkNameReserved: 6156;
+    /** `gift_key == sender` (Sentinel run-011; 6158-6229 are upgrade 6's). */
+    readonly GiftLinkKeyIsSender: 6231;
+};
+/** An ephemeral gift key: `secretKey` is the 64-byte Solana form (32-byte
+ *  seed ‖ 32-byte public key), so `Keypair.fromSecretKey(secretKey)` (web3.js)
+ *  signs the claim directly. */
+export interface GiftLinkKey {
+    /** base58 public key = the `gift_key`. */
+    readonly giftKey: string;
+    readonly secretKey: Uint8Array;
+}
+/** Derive the ed25519 public key of a 32-byte seed (WebCrypto). */
+export declare function giftKeyFromSeed(seed: Uint8Array): Promise<GiftLinkKey>;
+/**
+ * Generate a fresh ephemeral gift key (CSPRNG seed, WebCrypto Ed25519). One
+ * per link; never reuse it.
+ */
+export declare function newGiftLinkKey(): Promise<GiftLinkKey>;
+/** The shareable link: `<base>#k=<base58 64-byte secret key>`. The secret is
+ *  in the FRAGMENT so it never reaches a server log. */
+export declare function giftLinkUrl(key: Pick<GiftLinkKey, "secretKey">, base?: string): string;
+/**
+ * Read the gift key back out of a link (or a bare `#k=...` fragment). Accepts
+ * the 64-byte secret key (what {@link giftLinkUrl} writes) or a 32-byte seed.
+ * Re-derives the public key (WebCrypto) and, for the 64-byte form, refuses a
+ * secret whose embedded public key does not match its seed. Null when the
+ * link has no well-formed key.
+ */
+export declare function parseGiftLinkUrl(link: string): Promise<GiftLinkKey | null>;
+/** The escrow: `["gift", gift_key]`. */
+export declare function findGiftLinkPda(find: PdaFinder, programId: AddressLike, giftKey: AddressLike): Promise<string>;
+/** Decoded `GiftLink`. Addresses are base58. */
+export interface GiftLink {
+    readonly version: number;
+    readonly sender: string;
+    readonly giftKey: string;
+    readonly kind: GiftKindName;
+    /** XNT: lamports paid out. Name: the escrowed price snapshot. */
+    readonly amount: bigint;
+    /** Name gifts only; "" for XNT. */
+    readonly name: string;
+    readonly handleType: number;
+    readonly integrator: string | null;
+    readonly integratorRateBps: number;
+    readonly expiresAt: bigint;
+    readonly createdAt: bigint;
+    readonly bump: number;
+}
+/**
+ * Decode a raw `GiftLink` (discriminator included) in the Borsh order of
+ * state.rs: version u8 | sender | gift_key | kind u8 | amount u64 |
+ * name [u8;32] | name_len u8 | handle_type u8 | integrator Option<Pubkey> |
+ * integrator_rate_bps u16 | expires_at i64 | created_at i64 | bump u8.
+ * Null when the bytes are not a `GiftLink`.
+ */
+export declare function decodeGiftLink(data: Uint8Array): GiftLink | null;
+/** Fetch + decode a gift link by its escrow address (null if absent: never
+ *  created, or already claimed / refunded). */
+export declare function fetchGiftLink(rpc: RpcFn, address: AddressLike, opts?: {
+    readonly programId?: AddressLike;
+    readonly commitment?: string;
+}): Promise<{
+    readonly address: string;
+    readonly gift: GiftLink;
+    readonly lamports: bigint;
+} | null>;
+/** `now >= expiresAt`: claims fail, anyone may refund to the sender. */
+export declare function isGiftLinkExpired(g: Pick<GiftLink, "expiresAt">, nowSecs: bigint | number): boolean;
+/** The Borsh arguments of `create_gift_link` (after the discriminator):
+ *  `kind u8, amount u64, name String, handle_type u8, expires_at i64`. */
+export declare function encodeCreateGiftLinkArgs(a: {
+    readonly kind: GiftKindName;
+    readonly amount: bigint;
+    readonly name: string;
+    readonly handleType: number;
+    readonly expiresAt: bigint;
+}): Uint8Array;
+interface CreateGiftLinkBase {
+    readonly programId: AddressLike;
+    /** Signer; funds the escrow + rent and receives refunds. */
+    readonly sender: AddressLike;
+    /** Signer; the ephemeral gift key's PUBLIC key ({@link newGiftLinkKey}). */
+    readonly giftKey: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** {@link findGiftLinkPda}(giftKey). */
+    readonly gift: AddressLike;
+    /** Unix seconds; in the future and at most {@link MAX_GIFT_LINK_DURATION_SECS} ahead. */
+    readonly expiresAt: bigint;
+}
+export interface CreateXntGiftLinkParams extends CreateGiftLinkBase {
+    readonly kind: "xnt";
+    /** Lamports; at least the rent-exempt minimum of an empty account
+     *  (890 880 on X1), else `GiftAmountInvalid` (6151). */
+    readonly amount: bigint;
+}
+export interface CreateNameGiftLinkParams extends CreateGiftLinkBase {
+    readonly kind: "name";
+    /** Canonical bare name (no `@`), unregistered, no pending voucher. */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** `["handle", name]`. */
+    readonly handle: AddressLike;
+    /** `["voucher", name]`. */
+    readonly voucher: AddressLike;
+    /** Optional integrator pair (integrator.ts `integratorAccountsForCreateVoucher`). */
+    readonly integratorAccounts?: readonly InstructionKey[];
+}
+/**
+ * `create_gift_link(kind, amount, name, handle_type, expires_at)`. Accounts
+ * (`CreateGiftLink`): sender(s,w), gift_key(s), config, gift(w),
+ * system_program, then (name gifts) handle, voucher and the optional
+ * integrator pair. A name gift's escrow is priced by the program (the live
+ * price snapshot); `amount` is sent as 0.
+ */
+export declare function buildCreateGiftLinkIx(p: CreateXntGiftLinkParams | CreateNameGiftLinkParams): BuiltInstruction;
+export interface ClaimGiftLinkParams {
+    readonly programId: AddressLike;
+    /** Signer: the gift key from the link. */
+    readonly giftKey: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** {@link findGiftLinkPda}(giftKey). */
+    readonly gift: AddressLike;
+    /** `GiftLink.sender` (receives the escrow's rent). */
+    readonly sender: AddressLike;
+    /** The recipient's wallet: gets exactly `GiftLink.amount` lamports. */
+    readonly destination: AddressLike;
+}
+/** `claim_gift_link()` (XNT gifts). Accounts (`ClaimGiftLink`): gift_key(s),
+ *  config, gift(w), sender(w), destination(w). The fee payer is whoever
+ *  submits (not an account of this instruction). */
+export declare function buildClaimGiftLinkIx(p: ClaimGiftLinkParams): BuiltInstruction;
+export interface ClaimGiftLinkNameParams extends TokenizedTailAccounts {
+    readonly programId: AddressLike;
+    /** Signer; fronts the tx fee and every new account's rent (the rent is
+     *  reimbursed from the escrow). May be a relayer. */
+    readonly claimer: AddressLike;
+    /** Signer: the gift key from the link. */
+    readonly giftKey: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** `Config.treasury`. */
+    readonly treasury: AddressLike;
+    /** {@link findGiftLinkPda}(giftKey). */
+    readonly gift: AddressLike;
+    /** `GiftLink.sender`. */
+    readonly sender: AddressLike;
+    /** The destination wallet: owns the name and its pNFT. The tail's
+     *  `ownerTokenAccount` / `tokenRecord` derive against THIS address
+     *  (`deriveTokenizedNftAccounts(find, { programId, owner, handle })`). */
+    readonly owner: AddressLike;
+    /** `["handle", name]`. */
+    readonly handle: AddressLike;
+    /** `GiftLink.name`. */
+    readonly name: string;
+    /** REQUIRED iff `GiftLink.integrator` is set (must equal it). */
+    readonly integrator?: AddressLike;
+}
+/**
+ * `claim_gift_link_name(name)` (name gifts): registers the name to `owner` as
+ * a tokenized pNFT, exactly like `claim_voucher_tokenized`. Accounts
+ * (`ClaimGiftLinkName`): claimer(s,w), gift_key(s), config(w), treasury(w),
+ * gift(w), sender(w), owner, handle(w), then the 14-account pNFT tail, then
+ * the optional integrator(w). Prepend a ComputeBudget
+ * `SetComputeUnitLimit(CLAIM_GIFT_LINK_NAME_CU_LIMIT)`.
+ */
+export declare function buildClaimGiftLinkNameIx(p: ClaimGiftLinkNameParams): BuiltInstruction;
+export interface RefundGiftLinkParams {
+    readonly programId: AddressLike;
+    /** Signer: the sender (any time) or anyone (at/after `expiresAt`). */
+    readonly caller: AddressLike;
+    readonly gift: AddressLike;
+    /** `GiftLink.sender`: receives escrow + rent. */
+    readonly sender: AddressLike;
+}
+/** `refund_gift_link()`. Accounts (`RefundGiftLink`): caller(s), gift(w),
+ *  sender(w). */
+export declare function buildRefundGiftLinkIx(p: RefundGiftLinkParams): BuiltInstruction;
+/** Plain-language sentence for a gift-link error code (6151-6156, 6231), or null. */
+export declare function giftLinkErrorMessage(code: number): string | null;
+export {};