@x1id/resolve 0.2.1 → 0.3.0

package/dist/textRecords.js

@@ -0,0 +1,357 @@
+/**
+ * Generic string-keyed metadata records (`TextRecord` accounts, #7376) —
+ * profile fields (`website`, `avatar`), social usernames (`com.discord`,
+ * `com.github`, `com.x`), and the future `contenthash` (#7382) — read WITH
+ * the universal staleness rule from docs/record-trust.md structurally
+ * enforced, plus instruction builders for `create_text_record` /
+ * `update_text_record` / `close_text_record`.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return the
+ * transport-neutral {@link BuiltInstruction} `delegate.ts` defines; PDAs are
+ * NOT derived here (see delegate.ts's module docs for why — derive
+ * `["text", handlePda, sha256(key)]` with your runtime's canonical
+ * `findProgramAddress`, hashing the key via {@link hashTextKey}).
+ *
+ * # The seed is `sha256(key)`; the plaintext key is ALSO stored
+ *
+ * A Solana PDA seed maxes out at 32 bytes; a text-record key is up to 64.
+ * The program hashes the key (sha256 — NOT keccak, so this module's
+ * {@link hashTextKey} is plain WebCrypto with no dependency) and uses the
+ * FULL 32-byte digest as the third seed. The account stores the key in
+ * plaintext too, so {@link fetchTextRecords} enumerates a handle's keys
+ * without preimage guessing — the hash is wire plumbing, the field is the
+ * truth, and the program guarantees they agree (the same instruction
+ * argument feeds both).
+ *
+ * # Values are RAW BYTES
+ *
+ * The program enforces only a length cap (1..=256), deliberately not UTF-8 —
+ * load-bearing for `contenthash`, whose value is a binary multicodec.
+ * Rendering is a reader decision: {@link textValueToString} decodes strictly
+ * and returns null for binary values, which callers hex-render or handle by
+ * key (`records.ts`'s `valueToAddress` convention).
+ *
+ * # Why every read function here demands `registeredAt`
+ *
+ * The identical PDA-reuse hazard `records.ts` documents: a `Handle`'s
+ * address is a pure function of the name, release + re-register lands at
+ * the SAME pubkey, and a previous owner's website/avatar/socials would
+ * otherwise be rendered as the new owner's. The mandatory read-side rule
+ * (docs/record-trust.md, the universal rule):
+ *
+ *     text_record.updated_at >= handle.registered_at
+ *
+ * There is deliberately no way to decode or fetch a text record through
+ * this module without the handle's `registered_at` in hand.
+ *
+ * # These records count (#7384)
+ *
+ * `create_text_record` increments — and `close_text_record` decrements —
+ * the SAME `record_count` Handle extension as the address-record family
+ * (`recordCount.ts`), so `release_handle` refuses (`HandleHasRecords`,
+ * 6044) while any counted record of EITHER kind remains. Close every text
+ * record before releasing a handle, and pass the HANDLE account writable to
+ * create/close (the builders here do).
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { recordDelegateNonePlaceholder, recordDelegateSomeSlot } from "./delegate.js";
+/** Seed prefix of a text-record PDA: `["text", handlePda, sha256(key)]`. */
+export const TEXT_RECORD_SEED = "text";
+/** Max key length, BYTES of UTF-8 (program error `BadTextKey`, 6047). */
+export const TEXT_KEY_MAX_LEN = 64;
+/** Max value length, bytes (program error `BadTextValue`, 6048). */
+export const TEXT_VALUE_MAX_LEN = 256;
+// Well-known keys (ENS-style: bare names for generic fields, reverse-DNS for
+// service-specific ones). Any key up to 64 bytes is valid on-chain; these
+// constants exist so every surface spells the common ones identically.
+/** The handle's website URL. */
+export const TEXT_KEY_WEBSITE = "website";
+/** The handle's avatar image URL. */
+export const TEXT_KEY_AVATAR = "avatar";
+/** Discord username. */
+export const TEXT_KEY_DISCORD = "com.discord";
+/** GitHub username. */
+export const TEXT_KEY_GITHUB = "com.github";
+/** X (Twitter) username. */
+export const TEXT_KEY_X = "com.x";
+/** Decentralized-content hash (#7382) — value is BINARY (multicodec), not
+ *  text; {@link textValueToString} correctly returns null for it. */
+export const TEXT_KEY_CONTENTHASH = "contenthash";
+/** Every well-known key this SDK names, frozen, for pickers/iteration. */
+export const WELL_KNOWN_TEXT_KEYS = Object.freeze([
+    TEXT_KEY_WEBSITE,
+    TEXT_KEY_AVATAR,
+    TEXT_KEY_DISCORD,
+    TEXT_KEY_GITHUB,
+    TEXT_KEY_X,
+    TEXT_KEY_CONTENTHASH,
+]);
+/** Anchor account discriminator: `sha256("account:TextRecord")[0..8]`.
+ *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
+ *  everywhere it runs); asserted against a re-derivation in the test suite
+ *  so a typo can never silently pass. */
+export const TEXT_RECORD_DISCRIMINATOR = Uint8Array.from([
+    177, 94, 37, 181, 209, 75, 179, 30,
+]);
+/** Anchor instruction discriminator: `sha256("global:create_text_record")[0..8]`. */
+export const CREATE_TEXT_RECORD_DISCRIMINATOR = Uint8Array.from([
+    6, 129, 8, 35, 121, 55, 67, 149,
+]);
+/** Anchor instruction discriminator: `sha256("global:update_text_record")[0..8]`. */
+export const UPDATE_TEXT_RECORD_DISCRIMINATOR = Uint8Array.from([
+    233, 174, 2, 216, 24, 80, 99, 192,
+]);
+/** Anchor instruction discriminator: `sha256("global:close_text_record")[0..8]`. */
+export const CLOSE_TEXT_RECORD_DISCRIMINATOR = Uint8Array.from([
+    185, 179, 63, 132, 23, 60, 195, 219,
+]);
+/** `8 + TextRecord::INIT_SPACE` — the program allocates the full max
+ *  capacity, so every TextRecord account is exactly this long, live fields
+ *  packed at the front and the rest zero padding:
+ *  8 + 32 + (4 + 64) + (4 + 256) + 8 + 1. */
+export const TEXT_RECORD_LEN = 377;
+/** Byte offset of `handle` within a TextRecord account: the 8-byte
+ *  discriminator. */
+const TEXT_RECORD_HANDLE_OFFSET = 8;
+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) {
+    // Round-trip through bytes so a non-canonical base58 spelling and a byte
+    // input both come out identically.
+    return encodeBase58(toBytes32(v, what));
+}
+/**
+ * `sha256(utf8(key))` — the 32-byte third PDA seed for
+ * `["text", handlePda, hash]`. WebCrypto (`crypto.subtle`), so it is async
+ * and available in every modern browser, Node ≥ 18, and workers. The full
+ * digest is the seed, untruncated — mirrors the program's `text_key_hash`.
+ */
+export async function hashTextKey(key) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+    return new Uint8Array(digest);
+}
+/**
+ * Render stored value bytes as text: a STRICT UTF-8 decode, or null when the
+ * bytes are not valid UTF-8 (binary values like `contenthash`). Callers
+ * needing to show binary values render hex themselves — never a replacement-
+ * character decode, which would corrupt silently.
+ */
+export function textValueToString(value) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode one TextRecord account.
+ *
+ * TextRecord account layout, after the 8-byte Anchor discriminator:
+ *
+ *   handle: Pubkey(32)  key: String (u32 len + bytes, max 64)
+ *   value: Vec<u8> (u32 len + bytes, max 256)  updated_at: i64(8)  bump: u8(1)
+ *
+ * `registeredAt` is the owning Handle's `registered_at`, decoded by the
+ * caller from the Handle account — it decides `stale`. There is
+ * intentionally no overload without it (see the module docs).
+ *
+ * Returns null for anything that is not a TextRecord: wrong length, wrong
+ * discriminator, lengths that do not fit, or a key that is not valid UTF-8
+ * (the program's Borsh `String` guarantees it is, so that is not a
+ * TextRecord).
+ */
+export function decodeTextRecord(raw, account, registeredAt) {
+    if (raw.length !== TEXT_RECORD_LEN)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (raw[i] !== TEXT_RECORD_DISCRIMINATOR[i])
+            return null;
+    }
+    const dv = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    let o = 8;
+    const handle = encodeBase58(raw.slice(o, o + 32));
+    o += 32;
+    const keyLen = dv.getUint32(o, true);
+    o += 4;
+    // `#[max_len(64)]` — and every fixed field after must still fit.
+    if (keyLen > TEXT_KEY_MAX_LEN || o + keyLen + 4 > raw.length)
+        return null;
+    const keyBytes = raw.slice(o, o + keyLen);
+    o += keyLen;
+    const valueLen = dv.getUint32(o, true);
+    o += 4;
+    if (valueLen > TEXT_VALUE_MAX_LEN || o + valueLen + 8 + 1 > raw.length)
+        return null;
+    const value = raw.slice(o, o + valueLen);
+    o += valueLen;
+    const updatedAt = dv.getBigInt64(o, true);
+    const key = textValueToString(keyBytes);
+    if (key === null)
+        return null; // Borsh Strings are always valid UTF-8
+    return {
+        account,
+        handle,
+        key,
+        value,
+        text: textValueToString(value),
+        updatedAt,
+        stale: updatedAt < registeredAt,
+    };
+}
+/** The text records the CURRENT owner actually has — `stale` ones excluded.
+ *  This is the list to render on a profile and count. */
+export function liveTextRecords(records) {
+    return records.filter((r) => !r.stale);
+}
+/**
+ * Fetch every TextRecord account of a handle — one `getProgramAccounts`
+ * call, filtered by the RPC on size (377), the TextRecord discriminator at
+ * offset 0 and the handle pubkey at offset 8, then every byte re-checked
+ * locally (the node's filters are an optimisation, never the guarantee) —
+ * the exact shape of `fetchRecords`. Scoping the scan to the registry
+ * program id also IS the ownership check.
+ *
+ * `registeredAt` is `Handle.registered_at` as decoded from the Handle
+ * account the caller already has — the staleness rule needs it, and there
+ * is no variant of this function without it. Every record is returned,
+ * stale ones flagged, so an owner surface can show what a previous owner
+ * left behind; anything that renders a profile takes
+ * {@link liveTextRecords}.
+ */
+export async function fetchTextRecords(rpc, programId, handleAccount, registeredAt) {
+    const res = (await rpc("getProgramAccounts", [
+        programId,
+        {
+            encoding: "base64",
+            commitment: "confirmed",
+            filters: [
+                { dataSize: TEXT_RECORD_LEN },
+                { memcmp: { offset: 0, bytes: encodeBase58(TEXT_RECORD_DISCRIMINATOR) } },
+                { memcmp: { offset: TEXT_RECORD_HANDLE_OFFSET, bytes: handleAccount } },
+            ],
+        },
+    ]));
+    const out = [];
+    for (const a of res ?? []) {
+        const bin = atob(a.account.data[0]);
+        const raw = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            raw[i] = bin.charCodeAt(i);
+        const decoded = decodeTextRecord(raw, a.pubkey, registeredAt);
+        // Defence in depth: the memcmp filter should guarantee the handle
+        // match, but a wrong offset would silently attribute someone else's
+        // record to this handle. A malformed account is skipped, not fatal.
+        if (decoded && decoded.handle === handleAccount)
+            out.push(decoded);
+    }
+    out.sort((x, y) => x.key.localeCompare(y.key));
+    return out;
+}
+function pushAuthorityTail(keys, programId, p) {
+    if (p.recordDelegate !== undefined) {
+        keys.push(recordDelegateSomeSlot(p.recordDelegate));
+    }
+    else if (p.holderTokenAccount !== undefined) {
+        keys.push(recordDelegateNonePlaceholder(programId));
+    }
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({
+            pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"),
+            isSigner: false,
+            isWritable: false,
+        });
+    }
+}
+/** Borsh `String`/`Vec<u8>`: u32 LE length + bytes. */
+function encVec(bytes) {
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+function checkKey(key) {
+    const bytes = new TextEncoder().encode(key);
+    if (bytes.length === 0 || bytes.length > TEXT_KEY_MAX_LEN) {
+        throw new Error(`key must be 1..=${TEXT_KEY_MAX_LEN} bytes of UTF-8`);
+    }
+    return bytes;
+}
+function checkValue(value) {
+    if (value.length === 0 || value.length > TEXT_VALUE_MAX_LEN) {
+        throw new Error(`value must be 1..=${TEXT_VALUE_MAX_LEN} bytes`);
+    }
+    return value;
+}
+/**
+ * Build `create_text_record` — create the (handle, key) record, stamping
+ * `updated_at` from the Clock and incrementing the handle's record_count.
+ */
+export function buildCreateTextRecordIx(p) {
+    const keyBytes = checkKey(p.key);
+    const value = checkValue(p.value);
+    const encKey = encVec(keyBytes);
+    const encValue = encVec(value);
+    const data = new Uint8Array(8 + encKey.length + encValue.length);
+    data.set(CREATE_TEXT_RECORD_DISCRIMINATOR, 0);
+    data.set(encKey, 8);
+    data.set(encValue, 8 + encKey.length);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.textRecord, "textRecord"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `update_text_record` — replace the value and re-stamp `updated_at`
+ * (also how a record is re-adopted into a new ownership epoch).
+ */
+export function buildUpdateTextRecordIx(p) {
+    const value = checkValue(p.value);
+    const encValue = encVec(value);
+    const data = new Uint8Array(8 + encValue.length);
+    data.set(UPDATE_TEXT_RECORD_DISCRIMINATOR, 0);
+    data.set(encValue, 8);
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.textRecord, "textRecord"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `close_text_record` — close the record, rent to `recipient`,
+ * decrementing the handle's record_count. Close every text record before
+ * `release_handle` — for a counted handle that is enforced
+ * (`HandleHasRecords`), not advised.
+ */
+export function buildCloseTextRecordIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.textRecord, "textRecord"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    pushAuthorityTail(keys, p.programId, p);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: CLOSE_TEXT_RECORD_DISCRIMINATOR.slice(),
+    };
+}

package/dist/voucher.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Prepaid gift-registration vouchers (`PrepaidVoucher`, #7399): instruction
+ * builders and account decoding for `create_voucher` / `claim_voucher` /
+ * `refund_voucher`.
+ *
+ * Hand-rolled like the rest of this package — see `delegate.ts` for the
+ * web3.js adapter and `wasm.ts` for why PDAs are derived by the caller, not
+ * here.
+ *
+ * # Deriving the PDAs
+ *
+ * ```ts
+ * // the voucher itself
+ * PublicKey.findProgramAddressSync([Buffer.from(VOUCHER_SEED), Buffer.from(name)], programId);
+ * // the handle the claim will register (canonical name bytes)
+ * PublicKey.findProgramAddressSync([Buffer.from("handle"), Buffer.from(name)], programId);
+ * ```
+ *
+ * # Lifecycle (mirror of lib.rs)
+ *
+ * - `create_voucher(name, handleType, recipient, expiresAt)` escrows the mint
+ *   price (a snapshot of the live price) into `["voucher", name]` and reserves
+ *   the voucher slot. `recipient` bound ⇒ the claim registers the handle to
+ *   that wallet no matter who submits; `null` ⇒ open-code (the claimer owns
+ *   it). 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.
+ * - `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.
+ * - `refund_voucher(name)` returns the whole escrow (+ rent) to the payer,
+ *   payer-signed, only at/after `expiresAt`.
+ */
+import type { AddressLike, BuiltInstruction, InstructionKey } from "./delegate.js";
+/** Seed prefix of the voucher PDA: `["voucher", name]`. */
+export declare const VOUCHER_SEED = "voucher";
+/** 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]`. */
+export declare const CLAIM_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator `sha256("global:refund_voucher")[0..8]`. */
+export declare const REFUND_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** Anchor account discriminator `sha256("account:PrepaidVoucher")[0..8]`. */
+export declare const PREPAID_VOUCHER_DISCRIMINATOR: Uint8Array;
+/** `HandleType` (state.rs): descriptive only, does not gate anything. */
+export declare const HandleType: {
+    readonly Human: 0;
+    readonly Merchant: 1;
+    readonly Org: 2;
+    readonly Agent: 3;
+};
+export type HandleTypeValue = (typeof HandleType)[keyof typeof HandleType];
+/** Decoded `PrepaidVoucher` account. */
+export interface PrepaidVoucher {
+    /** Who funded it and gets the refund (base58). */
+    readonly payer: string;
+    /** Canonical name (no `@`). */
+    readonly name: string;
+    readonly handleType: number;
+    /** Escrowed mint fee, in lamports. */
+    readonly amount: bigint;
+    /** Bound recipient (base58) or null for an open-code voucher. */
+    readonly recipient: string | null;
+    /** Integrator referrer (base58) or null. */
+    readonly integrator: string | null;
+    /** Integrator share in basis points (meaningful only if `integrator`). */
+    readonly integratorRateBps: number;
+    readonly expiresAt: bigint;
+    readonly createdAt: bigint;
+    readonly bump: number;
+}
+/**
+ * Decode a `PrepaidVoucher` account's raw data, or null if not one. Parsed
+ * sequentially (Borsh): the two `Option<Pubkey>` fields are 1 byte when
+ * absent, 33 when present, so fixed offsets after them would be wrong.
+ */
+export declare function decodePrepaidVoucher(data: Uint8Array): PrepaidVoucher | null;
+export interface CreateVoucherParams {
+    readonly programId: AddressLike;
+    /** Funds the escrow + the voucher's rent. Signer. */
+    readonly payer: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The `["voucher", name]` PDA. */
+    readonly voucher: AddressLike;
+    /** The `["handle", name]` PDA — must be unregistered. */
+    readonly handle: AddressLike;
+    /** Canonical name (no `@`). */
+    readonly name: string;
+    readonly handleType: HandleTypeValue;
+    /** Bind the gift to this wallet, or null for open-code. */
+    readonly recipient?: AddressLike | null;
+    /** Unix seconds; must be strictly in the future. */
+    readonly expiresAt: bigint | number;
+    /** Optional integrator pair from `integratorAccountsForCreateVoucher`. */
+    readonly integratorAccounts?: readonly InstructionKey[];
+}
+/** Build `create_voucher`. */
+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. */
+    readonly claimer: AddressLike;
+    readonly config: AddressLike;
+    /** `Config.treasury`. */
+    readonly treasury: AddressLike;
+    readonly voucher: AddressLike;
+    /** The voucher's recorded payer — receives the voucher's rent on close. */
+    readonly voucherPayer: AddressLike;
+    /** The `["handle", name]` PDA being registered. */
+    readonly handle: AddressLike;
+    readonly name: string;
+    /** The integrator wallet — REQUIRED iff the voucher carries one; must equal
+     *  the voucher's `integrator`. Omit otherwise. */
+    readonly integrator?: AddressLike;
+}
+/** Build `claim_voucher`. */
+export declare function buildClaimVoucherIx(p: ClaimVoucherParams): BuiltInstruction;
+export interface RefundVoucherParams {
+    readonly programId: AddressLike;
+    /** The original payer. Signer; receives escrow + rent. */
+    readonly payer: AddressLike;
+    readonly voucher: AddressLike;
+    readonly name: string;
+}
+/** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
+export declare function buildRefundVoucherIx(p: RefundVoucherParams): BuiltInstruction;

package/dist/voucher.js

@@ -0,0 +1,185 @@
+/**
+ * Prepaid gift-registration vouchers (`PrepaidVoucher`, #7399): instruction
+ * builders and account decoding for `create_voucher` / `claim_voucher` /
+ * `refund_voucher`.
+ *
+ * Hand-rolled like the rest of this package — see `delegate.ts` for the
+ * web3.js adapter and `wasm.ts` for why PDAs are derived by the caller, not
+ * here.
+ *
+ * # Deriving the PDAs
+ *
+ * ```ts
+ * // the voucher itself
+ * PublicKey.findProgramAddressSync([Buffer.from(VOUCHER_SEED), Buffer.from(name)], programId);
+ * // the handle the claim will register (canonical name bytes)
+ * PublicKey.findProgramAddressSync([Buffer.from("handle"), Buffer.from(name)], programId);
+ * ```
+ *
+ * # Lifecycle (mirror of lib.rs)
+ *
+ * - `create_voucher(name, handleType, recipient, expiresAt)` escrows the mint
+ *   price (a snapshot of the live price) into `["voucher", name]` and reserves
+ *   the voucher slot. `recipient` bound ⇒ the claim registers the handle to
+ *   that wallet no matter who submits; `null` ⇒ open-code (the claimer owns
+ *   it). 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.
+ * - `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.
+ * - `refund_voucher(name)` returns the whole escrow (+ rent) to the payer,
+ *   payer-signed, only at/after `expiresAt`.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Seed prefix of the voucher PDA: `["voucher", name]`. */
+export const VOUCHER_SEED = "voucher";
+/** 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]`. */
+export const CLAIM_VOUCHER_DISCRIMINATOR = Uint8Array.from([229, 30, 138, 35, 188, 87, 230, 7]);
+/** Anchor instruction discriminator `sha256("global:refund_voucher")[0..8]`. */
+export const REFUND_VOUCHER_DISCRIMINATOR = Uint8Array.from([27, 159, 115, 120, 212, 202, 186, 248]);
+/** Anchor account discriminator `sha256("account:PrepaidVoucher")[0..8]`. */
+export const PREPAID_VOUCHER_DISCRIMINATOR = Uint8Array.from([159, 185, 203, 226, 62, 6, 57, 194]);
+/** `HandleType` (state.rs): descriptive only, does not gate anything. */
+export const HandleType = { Human: 0, Merchant: 1, Org: 2, Agent: 3 };
+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));
+}
+/** Borsh `String`: u32 LE length + UTF-8 bytes. */
+function encString(s) {
+    const bytes = new TextEncoder().encode(s);
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, true);
+    out.set(bytes, 4);
+    return out;
+}
+function encU64(v) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigInt64(0, v, true);
+    return out;
+}
+/**
+ * Decode a `PrepaidVoucher` account's raw data, or null if not one. Parsed
+ * sequentially (Borsh): the two `Option<Pubkey>` fields are 1 byte when
+ * absent, 33 when present, so fixed offsets after them would be wrong.
+ */
+export function decodePrepaidVoucher(data) {
+    if (data.length < 8 + 32 + 32 + 1 + 1 + 8 + 1 + 1 + 2 + 8 + 8 + 1)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== PREPAID_VOUCHER_DISCRIMINATOR[i])
+            return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let o = 8;
+    const payer = encodeBase58(data.slice(o, o + 32));
+    o += 32;
+    const nameBytes = data.slice(o, o + 32);
+    o += 32;
+    const nameLen = data[o];
+    o += 1;
+    const name = new TextDecoder().decode(nameBytes.slice(0, nameLen));
+    const handleType = data[o];
+    o += 1;
+    const amount = view.getBigUint64(o, true);
+    o += 8;
+    const recipientTag = data[o];
+    o += 1;
+    let recipient = null;
+    if (recipientTag === 1) {
+        recipient = encodeBase58(data.slice(o, o + 32));
+        o += 32;
+    }
+    const integratorTag = data[o];
+    o += 1;
+    let integrator = null;
+    if (integratorTag === 1) {
+        integrator = encodeBase58(data.slice(o, o + 32));
+        o += 32;
+    }
+    const integratorRateBps = view.getUint16(o, true);
+    o += 2;
+    const expiresAt = view.getBigInt64(o, true);
+    o += 8;
+    const createdAt = view.getBigInt64(o, true);
+    o += 8;
+    const bump = data[o];
+    return { payer, name, handleType, amount, recipient, integrator, integratorRateBps, expiresAt, createdAt, bump };
+}
+/** Build `create_voucher`. */
+export function buildCreateVoucherIx(p) {
+    const name = encString(p.name);
+    const recipient = p.recipient ?? null;
+    const recBytes = recipient === null ? Uint8Array.from([0]) : Uint8Array.from([1, ...toBytes32(recipient, "recipient")]);
+    const data = new Uint8Array(8 + name.length + 1 + recBytes.length + 8);
+    let o = 0;
+    data.set(CREATE_VOUCHER_DISCRIMINATOR, o);
+    o += 8;
+    data.set(name, o);
+    o += name.length;
+    data[o] = p.handleType;
+    o += 1;
+    data.set(recBytes, o);
+    o += recBytes.length;
+    data.set(encU64(BigInt(p.expiresAt)), o);
+    const keys = [
+        { pubkey: toBase58(p.payer, "payer"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.voucher, "voucher"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.integratorAccounts)
+        keys.push(...p.integratorAccounts);
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/** Build `claim_voucher`. */
+export function buildClaimVoucherIx(p) {
+    const name = encString(p.name);
+    const data = new Uint8Array(8 + name.length);
+    data.set(CLAIM_VOUCHER_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.handle, "handle"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, 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 };
+}
+/** Build `refund_voucher` — payer-signed, only valid at/after `expiresAt`. */
+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,
+    };
+}