@x1id/resolve 0.2.0 → 0.3.0

package/dist/delegate.js

@@ -0,0 +1,166 @@
+/**
+ * Delegated record-editing authority (`RecordDelegate`, #7374): instruction
+ * builders and account decoding for `set_record_delegate` /
+ * `revoke_record_delegate`, plus the optional-delegation account slot the
+ * record-editing instructions grew.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js` import (it stays an optional peer). Builders return a
+ * transport-neutral {@link BuiltInstruction}; adapt to web3.js with:
+ *
+ * ```ts
+ * new TransactionInstruction({
+ *   programId: new PublicKey(ix.programId),
+ *   keys: ix.keys.map((k) => ({ pubkey: new PublicKey(k.pubkey), isSigner: k.isSigner, isWritable: k.isWritable })),
+ *   data: Buffer.from(ix.data),
+ * });
+ * ```
+ *
+ * # Deriving the PDA
+ *
+ * The delegation account lives at `["delegate", handlePda]` under the
+ * registry program (seed constant: {@link RECORD_DELEGATE_SEED}). This module
+ * deliberately does NOT derive PDAs — `find_program_address` needs an
+ * ed25519 on-curve check, and this package's one rule about that is to never
+ * hand-roll it in TypeScript (see `wasm.ts`). Derive it with your runtime's
+ * canonical implementation, e.g. web3.js:
+ *
+ * ```ts
+ * PublicKey.findProgramAddressSync(
+ *   [Buffer.from(RECORD_DELEGATE_SEED), handlePda.toBytes()],
+ *   programId,
+ * );
+ * ```
+ *
+ * # The wire rules the on-chain program enforces (mirror of lib.rs)
+ *
+ * - `set_record_delegate` / `revoke_record_delegate` are gated by the STRICT
+ *   authority check: for a TOKENIZED handle append the holder's ATA for the
+ *   handle's NFT mint as the first extra (remaining) account.
+ * - The record-editing instructions (`create_record`, `update_record`,
+ *   `verify_record_*`, `close_record`) end in a named OPTIONAL
+ *   `record_delegate` account:
+ *   - a DELEGATE caller passes the delegation PDA there (and never any ATA);
+ *   - an untokenized OWNER simply omits the slot (pre-#7374 account list);
+ *   - a tokenized OWNER must pass the "explicitly None" placeholder — the
+ *     program id itself — in that slot, ahead of the ATA remaining account.
+ *     {@link recordDelegateNonePlaceholder} names that convention.
+ * - A delegation only authorizes while `delegatedAt >=
+ *   handle.registered_at`; any transfer/sale/recovery/re-registration bumps
+ *   the epoch and strands it (`StaleRecordDelegate`, code 6043). A bearer-NFT
+ *   marketplace trade does NOT bump the epoch — an NFT buyer should check
+ *   for, and revoke, an existing delegation.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+/** Seed prefix of the delegation PDA: `["delegate", handlePda]`. */
+export const RECORD_DELEGATE_SEED = "delegate";
+/** Anchor account discriminator: `sha256("account:RecordDelegate")[0..8]`. */
+export const RECORD_DELEGATE_DISCRIMINATOR = Uint8Array.from([
+    194, 175, 15, 64, 162, 184, 224, 111,
+]);
+/** Anchor instruction discriminator: `sha256("global:set_record_delegate")[0..8]`. */
+export const SET_RECORD_DELEGATE_DISCRIMINATOR = Uint8Array.from([
+    95, 62, 249, 218, 113, 197, 119, 51,
+]);
+/** Anchor instruction discriminator: `sha256("global:revoke_record_delegate")[0..8]`. */
+export const REVOKE_RECORD_DELEGATE_DISCRIMINATOR = Uint8Array.from([
+    53, 157, 215, 100, 80, 63, 168, 217,
+]);
+/** `RecordDelegate` account size: disc(8) handle(32) delegate(32) i64(8) bump(1). */
+export const RECORD_DELEGATE_LEN = 81;
+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));
+}
+/**
+ * Decode a `RecordDelegate` account's raw data (exactly what an RPC
+ * `getAccountInfo` returns for the `["delegate", handlePda]` PDA), or null if
+ * the bytes are not a `RecordDelegate`.
+ */
+export function decodeRecordDelegate(data) {
+    if (data.length !== RECORD_DELEGATE_LEN)
+        return null;
+    for (let i = 0; i < 8; i++) {
+        if (data[i] !== RECORD_DELEGATE_DISCRIMINATOR[i])
+            return null;
+    }
+    const delegatedAt = new DataView(data.buffer, data.byteOffset, data.byteLength).getBigInt64(72, true);
+    return {
+        handle: encodeBase58(data.slice(8, 40)),
+        delegate: encodeBase58(data.slice(40, 72)),
+        delegatedAt,
+        bump: data[80],
+    };
+}
+/**
+ * Build `set_record_delegate` — grant (or overwrite, re-stamping
+ * `delegatedAt`) the handle's single record-editing delegation.
+ */
+export function buildSetRecordDelegateIx(p) {
+    const data = new Uint8Array(8 + 32);
+    data.set(SET_RECORD_DELEGATE_DISCRIMINATOR, 0);
+    data.set(toBytes32(p.delegate, "delegate"), 8);
+    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: false },
+        { pubkey: toBase58(p.recordDelegate, "recordDelegate"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data };
+}
+/**
+ * Build `revoke_record_delegate` — close the delegation, rent to
+ * `recipient`. Also how a NEW owner/NFT-holder sweeps a previous owner's
+ * stale delegation.
+ */
+export function buildRevokeRecordDelegateIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.recordDelegate, "recordDelegate"), isSigner: false, isWritable: true },
+        { pubkey: toBase58(p.recipient, "recipient"), isSigner: false, isWritable: true },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys,
+        data: REVOKE_RECORD_DELEGATE_DISCRIMINATOR.slice(),
+    };
+}
+/**
+ * The named-optional-account "explicitly None" entry for a record-editing
+ * instruction's trailing `record_delegate` slot: Anchor's convention is the
+ * program's own id, read-only, non-signer. A TOKENIZED owner must place this
+ * ahead of their ATA remaining-account; an untokenized owner simply omits
+ * the slot instead.
+ */
+export function recordDelegateNonePlaceholder(programId) {
+    return { pubkey: toBase58(programId, "programId"), isSigner: false, isWritable: false };
+}
+/**
+ * The populated `record_delegate` slot a DELEGATE appends to a
+ * record-editing instruction's account list (read-only — the record
+ * instructions never mutate the delegation).
+ */
+export function recordDelegateSomeSlot(recordDelegate) {
+    return { pubkey: toBase58(recordDelegate, "recordDelegate"), isSigner: false, isWritable: false };
+}

package/dist/index.d.ts

@@ -2,9 +2,12 @@
  * Resolve `@handles` and X1NS names on X1.
  *
  * ```ts
- * import { createResolver } from "@x1id/resolve";
+ * import { createResolver, WasmResolver } from "@x1id/resolve";
  *
- * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz" });
+ * // bytes of @x1id/resolve/wasm/x1_resolve_wasm.wasm — see the README for loading
+ * const wasm = await WasmResolver.fromBytes(wasmBytes);
+ * // The @handle registry is on X1 testnet today; X1NS domains are on mainnet.
+ * const r = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
  * const res = await r.resolve("@jack", { chain: "X1" });
  * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
  * ```
@@ -25,8 +28,19 @@ export * from "./types.js";
 export { normalizeHandle, parseName, looksLikeName, type ParsedName } from "./parse.js";
 export { WasmResolver, type WasmTld } from "./wasm.js";
 export { encodeBase58, decodeBase58_32 } from "./base58.js";
+export { decodeRecord, liveRecords, chainForCoinType, valueToAddress, fetchRecords, RECORD_LEN, RECORD_DISC, type HandleRecord, } from "./records.js";
+export { buildControlChallenge, parseControlChallenge, generateControlNonce, createControlChallenge, verifyControlProof, verifyEd25519Strict, CONTROL_CHALLENGE_PREFIX, type ControlChallenge, type ControlConfig, type ControlProof, type ControlVerification, type ControlFailureReason, } 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";
 import { type Chain, type Resolved } from "./types.js";
 import { WasmResolver } from "./wasm.js";
+import { type HandleRecord } from "./records.js";
 export interface ResolverConfig {
     /** X1 RPC endpoint. */
     readonly rpcUrl: string;
@@ -59,6 +73,20 @@ export interface Resolver {
     resolve(input: string, opts?: ResolveOptions): Promise<Resolved>;
     /** Reverse: address to its primary name, or null if none is set. */
     reverse(address: string): Promise<string | null>;
+    /**
+     * Every per-chain payment record of a `@handle`, with the staleness rule
+     * of docs/record-trust.md already applied: records left behind by a
+     * previous registration of the same name (`updated_at <
+     * handle.registered_at`) come back flagged `stale` with `verified` forced
+     * false. Anything that resolves, displays, or counts must take
+     * `liveRecords(...)` of this; the full list exists so an owner surface
+     * can show what a previous owner left behind. `@handle` inputs only —
+     * X1NS domains keep their addresses elsewhere.
+     *
+     * @throws {ResolveError} `not-found` for an unregistered handle,
+     * `unrecognized` for a non-handle input.
+     */
+    records(input: string): Promise<readonly HandleRecord[]>;
     /** Clear the resolution cache. */
     clearCache(): void;
 }

package/dist/index.js

@@ -2,9 +2,12 @@
  * Resolve `@handles` and X1NS names on X1.
  *
  * ```ts
- * import { createResolver } from "@x1id/resolve";
+ * import { createResolver, WasmResolver } from "@x1id/resolve";
  *
- * const r = createResolver({ rpcUrl: "https://rpc.mainnet.x1.xyz" });
+ * // bytes of @x1id/resolve/wasm/x1_resolve_wasm.wasm — see the README for loading
+ * const wasm = await WasmResolver.fromBytes(wasmBytes);
+ * // The @handle registry is on X1 testnet today; X1NS domains are on mainnet.
+ * const r = createResolver({ rpcUrl: "https://rpc.testnet.x1.xyz", wasm });
  * const res = await r.resolve("@jack", { chain: "X1" });
  * // { name: "jack", namespace: "handle", address: "...", verification: "verified" }
  * ```
@@ -25,9 +28,21 @@ 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";
+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. */
@@ -37,85 +52,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) ...
-// The owner is the address the handle resolves to on X1.
-const HANDLE_OWNER_OFFSET = 41;
-const HANDLE_MIN_LEN = HANDLE_OWNER_OFFSET + 32;
-// `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;
-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");
@@ -126,48 +72,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) {
@@ -204,35 +108,65 @@ export function createResolver(config) {
             verification: "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 data = await accountData(encodeBase58(account));
-        if (!data) {
+        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) {
             throw new ResolveError("not-found", `@${canonical} is not registered`, input);
         }
-        if (data.length < HANDLE_MIN_LEN) {
+        const handle = parseHandleAccount(h.data);
+        if (!handle) {
             throw new ResolveError("rpc-error", `@${canonical} returned a malformed account`, input);
         }
-        const owner = encodeBase58(data.slice(HANDLE_OWNER_OFFSET, HANDLE_OWNER_OFFSET + 32));
-        // The owner 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));
+            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",
+            };
         }
-        return {
-            input,
-            name: canonical,
-            namespace: "handle",
-            address: owner,
-            chain,
-            // The owner holds the registry account for this handle — a proved control
-            // relationship, not an unverified record.
-            verification: "verified",
-        };
+        // Same authority rule as the program's `require_current_authority` and
+        // this resolver's `reverse()`: untokenized → `Handle.owner` (verified: it
+        // holds the registry account); tokenized → whoever holds the NFT right
+        // 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(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);
     }
     async function resolve(input, opts) {
         const chain = opts?.chain ?? "X1";
@@ -347,6 +281,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[];