@x1id/resolve 0.2.1 → 0.6.0

package/dist/index.js

@@ -28,9 +28,34 @@ export * from "./types.js";
 export { normalizeHandle, parseName, looksLikeName } from "./parse.js";
 export { WasmResolver } from "./wasm.js";
 export { encodeBase58, decodeBase58_32 } from "./base58.js";
-import { ResolveError } from "./types.js";
+export { decodeRecord, liveRecords, chainForCoinType, valueToAddress, fetchRecords, RECORD_LEN, RECORD_DISC, } from "./records.js";
+export { buildControlChallenge, parseControlChallenge, generateControlNonce, createControlChallenge, verifyControlProof, verifyEd25519Strict, CONTROL_CHALLENGE_PREFIX, } from "./control.js";
+export * from "./delegate.js";
+export * from "./subname.js";
+export * from "./recordCount.js";
+export * from "./attestation.js";
+export * from "./textRecords.js";
+export * from "./lock.js";
+export * from "./integrator.js";
+export * from "./voucher.js";
+export * from "./agent.js";
+export * from "./register.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
+// this decoder (the Handle account's `Option<Pubkey>` fields are
+// variable-width Borsh — a hand-rolled offset guess here would be exactly
+// the kind of drift docs/record-trust.md's "one implementation" rule
+// exists to prevent).
+export * from "./accounts.js";
+export * from "./x402.js";
+export * from "./recordWrite.js";
+export * from "./clearRecords.js";
+import { ResolveError, CHAIN_COIN_TYPE } from "./types.js";
 import { parseName } from "./parse.js";
 import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { DEFAULT_HANDLE_PROGRAM, TOKEN_ACCOUNT_MIN_LEN, bytesEqual, makeAccountReader, nftHolder, parseHandleAccount, readI64, readU64, } from "./accounts.js";
+import { fetchRecords, liveRecords } from "./records.js";
 /** Root authority for each X1NS TLD — used to verify a fetched account really
  *  belongs to the TLD it claims. Without this check a caller handed an
  *  arbitrary account would read an owner straight out of it. */
@@ -40,93 +65,16 @@ const TLD_ROOT = Object.freeze({
     xen: "3SUwpSz33AsyJwf6B48cKZuDTswuUEdUhcXszZrFWPqo",
 });
 const SPL_NAME_HEADER_LEN = 96;
-/** The @handle registry program on X1. Deployed on testnet today; the same id
- *  is used on mainnet once deployed. Override via `handleProgramId` to point at
- *  a different deployment. */
-const DEFAULT_HANDLE_PROGRAM = "8JgnNWi24bq9uzfnT9XmkWxvaWMVgoEs9bu8QsHhLe1P";
-// Handle account layout, mirrored from the on-chain program:
-//   discriminator(8) name(32) name_len(1) owner(32) ...
-// `owner` is the address an UNTOKENIZED handle resolves to. Once the handle
-// is tokenized (NFT extension present, see `parseHandleAccount`) the program
-// treats `owner` as informational only — authority is whoever holds the NFT —
-// and so must every reader.
-const HANDLE_OWNER_OFFSET = 41;
-// `Handle`'s fixed base allocation (`space = 8 + INIT_SPACE`). The NFT
-// extension, when present, is appended at this boundary regardless of the
-// compact Borsh length of the (variable, `Option`-bearing) struct content —
-// mirrors `Handle::NFT_EXT_OFFSET` in the program and `HANDLE_BASE_LEN` in
-// tools/api.
-const HANDLE_BASE_LEN = 8 + 149;
 // `Primary` pointer account (`["primary", owner]` under the registry):
 //   disc(8) | owner(32) | handle(32) | set_at(i64 LE, 8) | bump(1) = 81 bytes
 const PRIMARY_LEN = 81;
 const PRIMARY_HANDLE_OFFSET = 40;
 const PRIMARY_SET_AT_OFFSET = 72;
-// SPL Token account: mint(32) | owner(32) | amount(u64 LE, 8) | ...
-const TOKEN_ACCOUNT_MIN_LEN = 72;
-// SPL Token mint: mint_authority COption(4+32) | supply(u64 LE, 8) @36 | ...
-const MINT_SUPPLY_OFFSET = 36;
-const MINT_MIN_LEN = MINT_SUPPLY_OFFSET + 8;
-// The registry mints handle NFTs with the legacy SPL Token program, so every
-// token account for a handle mint is owned by it.
-const SPL_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
-function readI64(data, offset) {
-    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(offset, true);
-}
-function readU64(data, offset) {
-    return new DataView(data.buffer, data.byteOffset, data.byteLength).getBigUint64(offset, true);
-}
-function bytesEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++)
-        if (a[i] !== b[i])
-            return false;
-    return true;
-}
-/**
- * Parse the `Handle` fields the reverse rule needs. Port of `parse_handle` in
- * tools/api — sequential, because `recovery` / `recovery_target` are
- * `Option<Pubkey>` (Borsh: tag byte, then 32 bytes when `Some`) and shift
- * `registered_at`. The NFT mint is read at the fixed base boundary, not the
- * sequential position.
- *
- *   disc(8) name(32) name_len(1) owner(32) handle_type(1)
- *   recovery: Option<Pubkey>  recovery_initiated_at: i64
- *   recovery_target: Option<Pubkey>  registered_at: i64  bump(1)
- *   [at 8+149: nft tag(1) mint(32)]
- */
-function parseHandleAccount(data) {
-    if (data.length < HANDLE_BASE_LEN)
-        return null;
-    const nameLen = Math.min(data[40], 32);
-    const name = new TextDecoder().decode(data.slice(8, 8 + nameLen));
-    const owner = data.slice(HANDLE_OWNER_OFFSET, HANDLE_OWNER_OFFSET + 32);
-    let pos = 73 + 1; // owner end + handle_type(1)
-    // recovery: Option<Pubkey>
-    if (pos >= data.length)
-        return null;
-    pos += 1 + (data[pos] === 1 ? 32 : 0);
-    pos += 8; // recovery_initiated_at
-    // recovery_target: Option<Pubkey>
-    if (pos >= data.length)
-        return null;
-    pos += 1 + (data[pos] === 1 ? 32 : 0);
-    if (pos + 8 > data.length)
-        return null;
-    const registeredAt = readI64(data, pos);
-    const nftMint = data.length >= HANDLE_BASE_LEN + 33 && data[HANDLE_BASE_LEN] === 1
-        ? data.slice(HANDLE_BASE_LEN + 1, HANDLE_BASE_LEN + 33)
-        : null;
-    return { name, owner, registeredAt, nftMint };
-}
 export function createResolver(config) {
     const ttl = config.cacheTtlMs ?? 30_000;
     const cache = new Map();
-    const doFetch = config.fetchImpl ?? globalThis.fetch;
-    if (typeof doFetch !== "function") {
-        throw new Error("No fetch available; pass fetchImpl in ResolverConfig");
-    }
+    const reader = makeAccountReader(config.rpcUrl, config.fetchImpl);
+    const { rpc, accountInfo, accountData } = reader;
     const decodedProgram = decodeBase58_32(config.handleProgramId ?? DEFAULT_HANDLE_PROGRAM);
     if (!decodedProgram) {
         throw new Error("handleProgramId is not a valid base58 address");
@@ -137,48 +85,6 @@ export function createResolver(config) {
     // Re-encoded (not the caller's string) so a non-canonical base58 spelling of
     // the same key still compares equal to the RPC's `owner` field.
     const programBase58 = encodeBase58(handleProgram);
-    async function rpc(method, params) {
-        let res;
-        try {
-            res = await doFetch(config.rpcUrl, {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-            });
-        }
-        catch (e) {
-            throw new ResolveError("rpc-error", `RPC request failed: ${String(e)}`);
-        }
-        if (!res.ok) {
-            throw new ResolveError("rpc-error", `RPC returned HTTP ${res.status}`);
-        }
-        const body = (await res.json());
-        if (body.error) {
-            throw new ResolveError("rpc-error", body.error.message ?? "RPC error");
-        }
-        return body.result;
-    }
-    /** Fetch raw account data plus the owning program, or null when the account
-     *  does not exist. */
-    async function accountInfo(address) {
-        const result = (await rpc("getAccountInfo", [
-            address,
-            { encoding: "base64", commitment: "confirmed" },
-        ]));
-        const value = result?.value;
-        if (!value)
-            return null;
-        const b64 = value.data[0];
-        const bin = atob(b64);
-        const out = new Uint8Array(bin.length);
-        for (let i = 0; i < bin.length; i++)
-            out[i] = bin.charCodeAt(i);
-        return { data: out, owner: value.owner };
-    }
-    /** Fetch raw account data, or null when the account does not exist. */
-    async function accountData(address) {
-        return (await accountInfo(address))?.data ?? null;
-    }
     async function resolveX1ns(canonical, label, tld, chain, input) {
         const account = config.wasm.deriveX1nsAccount(label, tld);
         if (!account) {
@@ -215,62 +121,15 @@ export function createResolver(config) {
             verification: "unverified",
         };
     }
-    /**
-     * Current holder of a tokenized handle: the owner of the single token
-     * account holding the handle's NFT (supply 1, decimals 0). Never falls back
-     * to `Handle.owner` — after the NFT changes hands that field names the
-     * previous owner, and paying it is the exact failure this SDK exists to
-     * prevent.
-     *
-     * Parity with the program's `require_current_authority` (and this
-     * resolver's `reverse()`): the program recognises the holder as the name's
-     * authority only when the NFT sits in the holder's **associated token
-     * account** for the mint. A holder whose NFT is parked elsewhere (an
-     * auxiliary account, a program escrow) still controls the token, so the
-     * address is returned — but as `unverified`, because the registry will not
-     * let that address act for the name until the NFT is back in its ATA.
-     *
-     * A burned NFT (mint supply 0) is `not-found` with reason `nft-burned`: the
-     * name has no holder, and no one — least of all the stale `owner` — may be
-     * paid for it. Any other failure to find the holder is an `rpc-error`.
-     */
-    async function nftHolder(canonical, mint, input) {
-        const mintKey = encodeBase58(mint);
-        const largest = (await rpc("getTokenLargestAccounts", [
-            mintKey,
-            { commitment: "confirmed" },
-        ]));
-        const holders = (largest?.value ?? []).filter((a) => a.amount === "1");
-        if (holders.length !== 1) {
-            const m = await accountInfo(mintKey);
-            if (m &&
-                m.owner === SPL_TOKEN_PROGRAM &&
-                m.data.length >= MINT_MIN_LEN &&
-                readU64(m.data, MINT_SUPPLY_OFFSET) === 0n) {
-                throw new ResolveError("not-found", `@${canonical}'s NFT has been burned — the name has no holder`, input, "nft-burned");
-            }
-            throw new ResolveError("rpc-error", `@${canonical} is tokenized but its NFT has no single holder`, input);
-        }
-        const holdingAccount = holders[0].address;
-        const t = await accountInfo(holdingAccount);
-        if (!t ||
-            t.owner !== SPL_TOKEN_PROGRAM ||
-            t.data.length < TOKEN_ACCOUNT_MIN_LEN ||
-            !bytesEqual(t.data.slice(0, 32), mint) ||
-            readU64(t.data, 64) !== 1n) {
-            throw new ResolveError("rpc-error", `@${canonical} is tokenized but its NFT holder account is malformed`, input);
-        }
-        const holder = t.data.slice(32, 64);
-        const ata = config.wasm.deriveAssociatedTokenAccount(holder, mint);
-        const inAta = ata !== null && encodeBase58(ata) === holdingAccount;
-        return { address: encodeBase58(holder), verification: inAta ? "verified" : "unverified" };
-    }
-    async function resolveHandle(canonical, chain, input) {
+    /** Fetch and parse a handle's registry account, with the ownership check
+     *  every read path shares. */
+    async function fetchHandle(canonical, input) {
         const account = config.wasm.deriveHandleAccount(canonical, handleProgram);
         if (!account) {
             throw new ResolveError("invalid-handle", `"${input}" is not a valid handle`, input);
         }
-        const h = await accountInfo(encodeBase58(account));
+        const pda = encodeBase58(account);
+        const h = await accountInfo(pda);
         // An account at the PDA that the registry does not own is not a handle
         // (anyone can fund an address into existence) — the name is unregistered.
         if (!h || h.owner !== programBase58) {
@@ -280,11 +139,29 @@ export function createResolver(config) {
         if (!handle) {
             throw new ResolveError("rpc-error", `@${canonical} returned a malformed account`, input);
         }
-        // The address is an X1/SVM address. Per-chain records (ETH/BTC) live in
-        // separate record accounts the resolver does not read yet, so a request for
-        // another chain is an explicit "no record" rather than a wrong address.
+        return { pda, handle };
+    }
+    async function resolveHandle(canonical, chain, input) {
+        const { pda, handle } = await fetchHandle(canonical, input);
+        // ETH/BTC addresses live in per-chain `Record` accounts. Resolution goes
+        // through `fetchRecords`, which structurally applies the staleness rule of
+        // docs/record-trust.md (`updated_at >= registered_at`): a record left
+        // behind by a previous registration of the same name is never resolved,
+        // and a stale `verified: true` is never surfaced.
         if (chain !== "X1" && chain !== "SOL") {
-            throw new ResolveError("no-record-for-chain", `@${canonical} has no ${chain} record`, input);
+            const live = liveRecords(await fetchRecords(rpc, programBase58, pda, handle.registeredAt, handle.recordsClearedAt));
+            const record = live.find((r) => r.coinType === CHAIN_COIN_TYPE[chain]);
+            if (!record) {
+                throw new ResolveError("no-record-for-chain", `@${canonical} has no ${chain} record`, input);
+            }
+            return {
+                input,
+                name: canonical,
+                namespace: "handle",
+                address: record.address,
+                chain,
+                verification: record.verified ? "verified" : "unverified",
+            };
         }
         // Same authority rule as the program's `require_current_authority` and
         // this resolver's `reverse()`: untokenized → `Handle.owner` (verified: it
@@ -292,9 +169,18 @@ export function createResolver(config) {
         // now, verified only when it sits in that wallet's ATA (see `nftHolder`).
         const { address, verification } = handle.nftMint === null
             ? { address: encodeBase58(handle.owner), verification: "verified" }
-            : await nftHolder(canonical, handle.nftMint, input);
+            : await nftHolder(reader, config.wasm, canonical, handle.nftMint, input);
         return { input, name: canonical, namespace: "handle", address, chain, verification };
     }
+    /** See `Resolver.records`. */
+    async function records(input) {
+        const parsed = parseName(input); // throws with a specific code
+        if (parsed.namespace !== "handle") {
+            throw new ResolveError("unrecognized", `per-chain records exist only for @handles, not .${parsed.namespace} domains`, input);
+        }
+        const { pda, handle } = await fetchHandle(parsed.canonical, input);
+        return fetchRecords(rpc, programBase58, pda, handle.registeredAt, handle.recordsClearedAt);
+    }
     async function resolve(input, opts) {
         const chain = opts?.chain ?? "X1";
         const parsed = parseName(input); // throws with a specific code
@@ -408,6 +294,7 @@ export function createResolver(config) {
     return {
         resolve,
         reverse,
+        records,
         clearCache: () => cache.clear(),
     };
 }

package/dist/integrator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Integrator revenue-share (`AllowlistEntry`, #7397): instruction builders and
+ * account decoding for the admin allowlist (`add_integrator` /
+ * `set_integrator_rate` / `remove_integrator`), plus the two OPTIONAL trailing
+ * accounts `register` (and `create_voucher`) grew so a mint fee can be split
+ * on-chain with an allowlisted integrator.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. Builders return a transport-neutral
+ * {@link BuiltInstruction}; adapt to web3.js with the two-line snippet in
+ * `delegate.ts`.
+ *
+ * # Deriving the PDA
+ *
+ * The allowlist entry lives at `["integrator", integratorWallet]` under the
+ * registry program (seed constant {@link INTEGRATOR_SEED}). This module does
+ * NOT derive PDAs (see `wasm.ts`'s one rule); derive with web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(INTEGRATOR_SEED), integratorWallet.toBytes()],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The wire rules the program enforces (mirror of lib.rs)
+ *
+ * - `register` / `create_voucher` end in TWO optional, trailing accounts:
+ *   the integrator's fee-recipient WALLET (writable in `register`, read-only
+ *   in `create_voucher`) then its `["integrator", wallet]` `AllowlistEntry`.
+ *   Supply BOTH to split, or NEITHER to route 100% to treasury (the
+ *   pre-feature account list, byte-for-byte). Supplying exactly one fails
+ *   closed (`IntegratorNotAllowed`, code 6054). Use
+ *   {@link integratorAccountsForRegister} / {@link integratorAccountsForCreateVoucher}
+ *   to build the pair.
+ * - The rate is read from the on-chain `AllowlistEntry`, never trusted from
+ *   the transaction. It is capped at {@link MAX_INTEGRATOR_RATE_BPS} (40%);
+ *   {@link DEFAULT_INTEGRATOR_RATE_BPS} (20%) applies when `add_integrator`
+ *   omits a rate.
+ */
+import type { AddressLike, BuiltInstruction, InstructionKey } from "./delegate.js";
+/** Seed prefix of the allowlist PDA: `["integrator", integratorWallet]`. */
+export declare const INTEGRATOR_SEED = "integrator";
+/** Default integrator share when `add_integrator` omits a rate: 20%. */
+export declare const DEFAULT_INTEGRATOR_RATE_BPS = 2000;
+/** Hard cap on an integrator's share of a mint fee: 40%. */
+export declare const MAX_INTEGRATOR_RATE_BPS = 4000;
+/** Anchor instruction discriminator `sha256("global:add_integrator")[0..8]`. */
+export declare const ADD_INTEGRATOR_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator `sha256("global:set_integrator_rate")[0..8]`. */
+export declare const SET_INTEGRATOR_RATE_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator `sha256("global:remove_integrator")[0..8]`. */
+export declare const REMOVE_INTEGRATOR_DISCRIMINATOR: Uint8Array;
+/** Anchor account discriminator `sha256("account:AllowlistEntry")[0..8]`. */
+export declare const ALLOWLIST_ENTRY_DISCRIMINATOR: Uint8Array;
+/** `AllowlistEntry` account size: disc(8) integrator(32) rate_bps(u16, 2) bump(1). */
+export declare const ALLOWLIST_ENTRY_LEN = 43;
+/** Decoded `AllowlistEntry` account. */
+export interface AllowlistEntry {
+    /** The integrator's fee-recipient wallet (base58); equals the PDA seed. */
+    readonly integrator: string;
+    /** Share of the mint fee, in basis points (`<= MAX_INTEGRATOR_RATE_BPS`). */
+    readonly rateBps: number;
+    readonly bump: number;
+}
+/** Decode an `AllowlistEntry` account's raw data, or null if not one. */
+export declare function decodeAllowlistEntry(data: Uint8Array): AllowlistEntry | null;
+export interface AddIntegratorParams {
+    readonly programId: AddressLike;
+    /** `Config.admin`. Signer + rent payer for the new entry. */
+    readonly admin: AddressLike;
+    /** The `["config"]` PDA. */
+    readonly config: AddressLike;
+    /** The integrator's fee-recipient wallet (also the entry's seed). */
+    readonly integrator: AddressLike;
+    /** The `["integrator", integrator]` PDA — derive per the module docs. */
+    readonly integratorAllowlist: AddressLike;
+    /** Basis points (`<= MAX_INTEGRATOR_RATE_BPS`). Omit for the 20% default. */
+    readonly rateBps?: number;
+}
+/** Build `add_integrator` — allowlist an integrator at `rateBps` (or the 20%
+ *  default when omitted). Admin-only. */
+export declare function buildAddIntegratorIx(p: AddIntegratorParams): BuiltInstruction;
+export interface SetIntegratorRateParams {
+    readonly programId: AddressLike;
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    /** The `["integrator", integrator]` PDA being re-rated. */
+    readonly integratorAllowlist: AddressLike;
+    readonly rateBps: number;
+}
+/** Build `set_integrator_rate` — change an allowlisted integrator's rate.
+ *  Admin-only; `rateBps <= MAX_INTEGRATOR_RATE_BPS`. */
+export declare function buildSetIntegratorRateIx(p: SetIntegratorRateParams): BuiltInstruction;
+export interface RemoveIntegratorParams {
+    readonly programId: AddressLike;
+    readonly admin: AddressLike;
+    readonly config: AddressLike;
+    /** The `["integrator", integrator]` PDA being closed (rent to `admin`). */
+    readonly integratorAllowlist: AddressLike;
+}
+/** Build `remove_integrator` — close the allowlist entry, rent to the admin.
+ *  Admin-only. */
+export declare function buildRemoveIntegratorIx(p: RemoveIntegratorParams): BuiltInstruction;
+/**
+ * The two trailing optional accounts to append to a `register` instruction so
+ * an allowlisted integrator earns its split: `[integratorWallet (writable),
+ * ["integrator", wallet] entry (read-only)]`. Append BOTH or NEITHER — see the
+ * module docs.
+ */
+export declare function integratorAccountsForRegister(integrator: AddressLike, integratorAllowlist: AddressLike): InstructionKey[];
+/**
+ * Same as {@link integratorAccountsForRegister} but for `create_voucher`,
+ * where the wallet is READ-ONLY (nothing is paid at create; the rate is
+ * snapshotted onto the voucher).
+ */
+export declare function integratorAccountsForCreateVoucher(integrator: AddressLike, integratorAllowlist: AddressLike): InstructionKey[];

package/dist/integrator.js

@@ -0,0 +1,166 @@
+/**
+ * Integrator revenue-share (`AllowlistEntry`, #7397): instruction builders and
+ * account decoding for the admin allowlist (`add_integrator` /
+ * `set_integrator_rate` / `remove_integrator`), plus the two OPTIONAL trailing
+ * accounts `register` (and `create_voucher`) grew so a mint fee can be split
+ * on-chain with an allowlisted integrator.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import. Builders return a transport-neutral
+ * {@link BuiltInstruction}; adapt to web3.js with the two-line snippet in
+ * `delegate.ts`.
+ *
+ * # Deriving the PDA
+ *
+ * The allowlist entry lives at `["integrator", integratorWallet]` under the
+ * registry program (seed constant {@link INTEGRATOR_SEED}). This module does
+ * NOT derive PDAs (see `wasm.ts`'s one rule); derive with web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(INTEGRATOR_SEED), integratorWallet.toBytes()],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The wire rules the program enforces (mirror of lib.rs)
+ *
+ * - `register` / `create_voucher` end in TWO optional, trailing accounts:
+ *   the integrator's fee-recipient WALLET (writable in `register`, read-only
+ *   in `create_voucher`) then its `["integrator", wallet]` `AllowlistEntry`.
+ *   Supply BOTH to split, or NEITHER to route 100% to treasury (the
+ *   pre-feature account list, byte-for-byte). Supplying exactly one fails
+ *   closed (`IntegratorNotAllowed`, code 6054). Use
+ *   {@link integratorAccountsForRegister} / {@link integratorAccountsForCreateVoucher}
+ *   to build the pair.
+ * - The rate is read from the on-chain `AllowlistEntry`, never trusted from
+ *   the transaction. It is capped at {@link MAX_INTEGRATOR_RATE_BPS} (40%);
+ *   {@link DEFAULT_INTEGRATOR_RATE_BPS} (20%) applies when `add_integrator`
+ *   omits a rate.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Seed prefix of the allowlist PDA: `["integrator", integratorWallet]`. */
+export const INTEGRATOR_SEED = "integrator";
+/** Default integrator share when `add_integrator` omits a rate: 20%. */
+export const DEFAULT_INTEGRATOR_RATE_BPS = 2_000;
+/** Hard cap on an integrator's share of a mint fee: 40%. */
+export const MAX_INTEGRATOR_RATE_BPS = 4_000;
+/** Anchor instruction discriminator `sha256("global:add_integrator")[0..8]`. */
+export const ADD_INTEGRATOR_DISCRIMINATOR = Uint8Array.from([85, 249, 72, 201, 17, 187, 227, 38]);
+/** Anchor instruction discriminator `sha256("global:set_integrator_rate")[0..8]`. */
+export const SET_INTEGRATOR_RATE_DISCRIMINATOR = Uint8Array.from([104, 23, 19, 77, 35, 8, 161, 101]);
+/** Anchor instruction discriminator `sha256("global:remove_integrator")[0..8]`. */
+export const REMOVE_INTEGRATOR_DISCRIMINATOR = Uint8Array.from([162, 208, 67, 99, 105, 234, 199, 31]);
+/** Anchor account discriminator `sha256("account:AllowlistEntry")[0..8]`. */
+export const ALLOWLIST_ENTRY_DISCRIMINATOR = Uint8Array.from([42, 59, 88, 1, 124, 138, 92, 236]);
+/** `AllowlistEntry` account size: disc(8) integrator(32) rate_bps(u16, 2) bump(1). */
+export const ALLOWLIST_ENTRY_LEN = 43;
+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));
+}
+/** Decode an `AllowlistEntry` account's raw data, or null if not one. */
+export function decodeAllowlistEntry(data) {
+    if (data.length !== ALLOWLIST_ENTRY_LEN)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== ALLOWLIST_ENTRY_DISCRIMINATOR[i])
+            return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return {
+        integrator: encodeBase58(data.slice(8, 40)),
+        rateBps: view.getUint16(40, true),
+        bump: data[42],
+    };
+}
+/** Build `add_integrator` — allowlist an integrator at `rateBps` (or the 20%
+ *  default when omitted). Admin-only. */
+export function buildAddIntegratorIx(p) {
+    if (p.rateBps !== undefined && (p.rateBps < 0 || p.rateBps > MAX_INTEGRATOR_RATE_BPS || !Number.isInteger(p.rateBps))) {
+        throw new Error(`rateBps must be an integer in [0, ${MAX_INTEGRATOR_RATE_BPS}]`);
+    }
+    // disc(8) + integrator(32) + Option<u16> (tag[+ u16 LE]).
+    const hasRate = p.rateBps !== undefined;
+    const data = new Uint8Array(8 + 32 + 1 + (hasRate ? 2 : 0));
+    data.set(ADD_INTEGRATOR_DISCRIMINATOR, 0);
+    data.set(toBytes32(p.integrator, "integrator"), 8);
+    data[40] = hasRate ? 1 : 0;
+    if (hasRate)
+        new DataView(data.buffer).setUint16(41, p.rateBps, true);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+            { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+            { pubkey: toBase58(p.integratorAllowlist, "integratorAllowlist"), isSigner: false, isWritable: true },
+            { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+        ],
+        data,
+    };
+}
+/** Build `set_integrator_rate` — change an allowlisted integrator's rate.
+ *  Admin-only; `rateBps <= MAX_INTEGRATOR_RATE_BPS`. */
+export function buildSetIntegratorRateIx(p) {
+    if (p.rateBps < 0 || p.rateBps > MAX_INTEGRATOR_RATE_BPS || !Number.isInteger(p.rateBps)) {
+        throw new Error(`rateBps must be an integer in [0, ${MAX_INTEGRATOR_RATE_BPS}]`);
+    }
+    const data = new Uint8Array(8 + 2);
+    data.set(SET_INTEGRATOR_RATE_DISCRIMINATOR, 0);
+    new DataView(data.buffer).setUint16(8, p.rateBps, true);
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: false },
+            { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+            { pubkey: toBase58(p.integratorAllowlist, "integratorAllowlist"), isSigner: false, isWritable: true },
+        ],
+        data,
+    };
+}
+/** Build `remove_integrator` — close the allowlist entry, rent to the admin.
+ *  Admin-only. */
+export function buildRemoveIntegratorIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            { pubkey: toBase58(p.admin, "admin"), isSigner: true, isWritable: true },
+            { pubkey: toBase58(p.config, "config"), isSigner: false, isWritable: false },
+            { pubkey: toBase58(p.integratorAllowlist, "integratorAllowlist"), isSigner: false, isWritable: true },
+        ],
+        data: REMOVE_INTEGRATOR_DISCRIMINATOR.slice(),
+    };
+}
+/**
+ * The two trailing optional accounts to append to a `register` instruction so
+ * an allowlisted integrator earns its split: `[integratorWallet (writable),
+ * ["integrator", wallet] entry (read-only)]`. Append BOTH or NEITHER — see the
+ * module docs.
+ */
+export function integratorAccountsForRegister(integrator, integratorAllowlist) {
+    return [
+        { pubkey: toBase58(integrator, "integrator"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(integratorAllowlist, "integratorAllowlist"), isSigner: false, isWritable: false },
+    ];
+}
+/**
+ * Same as {@link integratorAccountsForRegister} but for `create_voucher`,
+ * where the wallet is READ-ONLY (nothing is paid at create; the rate is
+ * snapshotted onto the voucher).
+ */
+export function integratorAccountsForCreateVoucher(integrator, integratorAllowlist) {
+    return [
+        { pubkey: toBase58(integrator, "integrator"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(integratorAllowlist, "integratorAllowlist"), isSigner: false, isWritable: false },
+    ];
+}