@x1id/resolve 0.23.0 → 0.44.0

package/dist/pay.js

@@ -0,0 +1,756 @@
+/**
+ * X1ID Pay, phase 1: on-chain invoices (docs/specs/x1id-pay-onchain.md).
+ *
+ * The registry program (`x1-handles`) holds three Pay accounts:
+ *
+ * - `PayConfig` at `["pay_config"]`: the protocol fee (`fee_bps`, hard cap
+ *   {@link PAY_FEE_BPS_MAX}). While it does not exist the fee is 0.
+ * - `Invoice` at `["invoice", payee, id]`: one payment request. Its own
+ *   address is the Solana Pay reference, so `getSignaturesForAddress(invoice)`
+ *   finds the payment.
+ * - `MerchantAuthority` at `["merchant", payee, delegate]`: lets a merchant's
+ *   server key create and cancel invoices that always pay the merchant.
+ *
+ * Every Pay instruction is routed through the program's `fallback`
+ * (`extra_ix`), so none of them is in the generated IDL. They are encoded
+ * here by hand, like `set_namespace_pricing` in `namespacePricing.ts`:
+ * `sha256("global:<name>")[..8]` followed by raw Borsh arguments, with
+ * accounts in EXACTLY the order of the program's `Accounts` structs.
+ *
+ * Optional accounts follow Anchor's convention: a skipped optional slot that
+ * precedes a used one is the program id ("None"); trailing unused slots are
+ * simply left off.
+ *
+ * Hand-rolled like the rest of this package: no Anchor client, no
+ * `@solana/web3.js`. PDAs come through an injected {@link PdaFinder}.
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+import { DEFAULT_HANDLE_PROGRAM, makeAccountReader } from "./accounts.js";
+import { sha256 } from "./sha256.js";
+// ---------------------------------------------------------------------------
+// constants (mirror programs/x1-handles/src/{lib,state}.rs)
+// ---------------------------------------------------------------------------
+/** Hard cap on the Pay protocol fee in basis points (1%). */
+export const PAY_FEE_BPS_MAX = 100;
+/** The X1 record slot a name's payment address is read from. */
+export const PAY_X1_COIN_TYPE = 5_010_000;
+/** `Invoice.mint` for native XNT (`Pubkey::default()`). */
+export const INVOICE_NATIVE_MINT = "11111111111111111111111111111111";
+/** Length of an invoice id (`[u8; 16]`). */
+export const INVOICE_ID_LEN = 16;
+export const PAY_CONFIG_SEED = "pay_config";
+export const INVOICE_SEED = "invoice";
+export const MERCHANT_AUTHORITY_SEED = "merchant";
+/** Allocated size of each account (8-byte discriminator + `INIT_SPACE`). */
+export const PAY_CONFIG_ACCOUNT_LEN = 8 + 12;
+export const INVOICE_ACCOUNT_LEN = 8 + 268;
+export const MERCHANT_AUTHORITY_ACCOUNT_LEN = 8 + 74;
+/** Byte offsets inside a raw `Invoice` account, for `getProgramAccounts`
+ *  `memcmp` filters. Only fields before the variable-width `handle` are fixed. */
+export const INVOICE_OFFSETS = {
+    version: 8,
+    payee: 9,
+    creator: 41,
+    id: 73,
+    mint: 89,
+    amount: 121,
+    expiresAt: 129,
+    status: 137,
+    paidBy: 138,
+    paidAt: 170,
+    handle: 178,
+};
+const d8 = (...b) => Uint8Array.from(b);
+/** `sha256("global:set_pay_config")[..8]`. */
+export const SET_PAY_CONFIG_DISCRIMINATOR = d8(9, 248, 66, 110, 133, 99, 13, 55);
+/** `sha256("global:create_invoice")[..8]`. */
+export const CREATE_INVOICE_DISCRIMINATOR = d8(154, 170, 31, 135, 134, 100, 156, 146);
+/** `sha256("global:pay_invoice")[..8]`. */
+export const PAY_INVOICE_DISCRIMINATOR = d8(104, 6, 62, 239, 197, 206, 208, 220);
+/** `sha256("global:cancel_invoice")[..8]`. */
+export const CANCEL_INVOICE_DISCRIMINATOR = d8(88, 158, 54, 49, 53, 26, 92, 68);
+/** `sha256("global:close_invoice")[..8]`. */
+export const CLOSE_INVOICE_DISCRIMINATOR = d8(217, 64, 46, 247, 231, 36, 118, 252);
+/** `sha256("global:create_merchant_authority")[..8]`. */
+export const CREATE_MERCHANT_AUTHORITY_DISCRIMINATOR = d8(164, 168, 136, 143, 229, 233, 128, 171);
+/** `sha256("global:revoke_merchant_authority")[..8]`. */
+export const REVOKE_MERCHANT_AUTHORITY_DISCRIMINATOR = d8(64, 229, 132, 124, 172, 101, 15, 105);
+/** `sha256("account:Invoice")[..8]`. */
+export const INVOICE_ACCOUNT_DISCRIMINATOR = d8(51, 194, 250, 114, 6, 104, 18, 164);
+/** `sha256("account:PayConfig")[..8]`. */
+export const PAY_CONFIG_ACCOUNT_DISCRIMINATOR = d8(46, 180, 219, 72, 57, 225, 101, 83);
+/** `sha256("account:MerchantAuthority")[..8]`. */
+export const MERCHANT_AUTHORITY_ACCOUNT_DISCRIMINATOR = d8(223, 239, 26, 237, 235, 231, 118, 252);
+/** Program error codes added by Pay phase 1 (`RegistryError`, 6121-6135),
+ *  plus `InvoiceTermsChanged` (6136, Sentinel run-007): `pay_invoice`'s
+ *  pinned `expected_amount`/`expected_mint` no longer match the invoice. */
+export const PAY_ERRORS = {
+    PayFeeAboveMax: 6121,
+    PayConfigMismatch: 6122,
+    InvoiceAmountZero: 6123,
+    InvoiceExpiryInPast: 6124,
+    NotMerchantDelegate: 6125,
+    PayeeNotNamePaymentAddress: 6126,
+    PayeeNoLongerHoldsName: 6127,
+    InvoiceHandleMismatch: 6128,
+    InvoiceNotOpen: 6129,
+    InvoiceExpired: 6130,
+    InvoiceMintMismatch: 6131,
+    InvoicePayeeMismatch: 6132,
+    InvoiceTreasuryMismatch: 6133,
+    NotInvoiceCloser: 6134,
+    InvoiceStillOpen: 6135,
+    InvoiceTermsChanged: 6136,
+};
+/** Anchor's `InstructionFallbackNotFound`: the deployed program predates Pay. */
+export const PAY_NOT_DEPLOYED_ERROR = 101;
+/** `Invoice.status` as stored (Borsh enum index). */
+export const INVOICE_STATUS = { Open: 0, Paid: 1, Cancelled: 2 };
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const PAY_ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+const TE = new TextEncoder();
+const U64_MAX = 0xffffffffffffffffn;
+const I64_MAX = 0x7fffffffffffffffn;
+// ---------------------------------------------------------------------------
+// encoding helpers
+// ---------------------------------------------------------------------------
+function toBytes32(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function toBase58(v, what) {
+    return encodeBase58(toBytes32(v, what));
+}
+function key(pubkey, what, isSigner, isWritable) {
+    return { pubkey: toBase58(pubkey, what), isSigner, isWritable };
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((a, p) => a + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+function u16le(n) {
+    const out = new Uint8Array(2);
+    new DataView(out.buffer).setUint16(0, n, true);
+    return out;
+}
+function u32le(n) {
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, n, true);
+    return out;
+}
+function u64le(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, n, true);
+    return out;
+}
+function i64le(n) {
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigInt64(0, n, true);
+    return out;
+}
+function hasPrefix(data, disc) {
+    if (data.length < disc.length)
+        return false;
+    for (let i = 0; i < disc.length; i++)
+        if (data[i] !== disc[i])
+            return false;
+    return true;
+}
+function checkId(id) {
+    if (!(id instanceof Uint8Array) || id.length !== INVOICE_ID_LEN) {
+        throw new Error(`invoice id must be exactly ${INVOICE_ID_LEN} bytes`);
+    }
+    return id;
+}
+// ---------------------------------------------------------------------------
+// pure helpers
+// ---------------------------------------------------------------------------
+/** The fee `pay_invoice` takes from `amount` at `feeBps`: `amount * feeBps /
+ *  10_000`, rounded down (the program's u128 `pay_fee`). The payer always pays
+ *  exactly `amount`; the payee receives `amount - fee`. */
+export function payFee(amount, feeBps) {
+    if (typeof amount !== "bigint" || amount < 0n || amount > U64_MAX)
+        throw new Error("amount must be a u64 bigint");
+    if (!Number.isInteger(feeBps) || feeBps < 0 || feeBps > 0xffff)
+        throw new Error("feeBps must be a u16");
+    // The program clamps the stored rate to the cap before using it.
+    const bps = BigInt(Math.min(feeBps, PAY_FEE_BPS_MAX));
+    return (amount * bps) / 10000n;
+}
+/** {@link payFee} as a full split. */
+export function paySplit(amount, feeBps) {
+    const fee = payFee(amount, feeBps);
+    return { amount, fee, payeeReceives: amount - fee };
+}
+/** 16 fresh random bytes for a new invoice id (CSPRNG). */
+export function newInvoiceId() {
+    const c = globalThis.crypto;
+    if (!c?.getRandomValues)
+        throw new Error("No CSPRNG available (globalThis.crypto.getRandomValues)");
+    return c.getRandomValues(new Uint8Array(INVOICE_ID_LEN));
+}
+/** Lowercase hex of an invoice id (the form used in links). */
+export function invoiceIdToHex(id) {
+    return Array.from(checkId(id), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Parse a 32-character hex invoice id; null when malformed. */
+export function invoiceIdFromHex(hex) {
+    if (typeof hex !== "string" || !/^[0-9a-fA-F]{32}$/.test(hex))
+        return null;
+    const out = new Uint8Array(INVOICE_ID_LEN);
+    for (let i = 0; i < INVOICE_ID_LEN; i++)
+        out[i] = parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+    return out;
+}
+/** `memo_hash` for an off-chain description: sha256 of its UTF-8 bytes. An
+ *  empty description hashes to all zeros (no memo). */
+export function invoiceMemoHash(text) {
+    if (text === "")
+        return new Uint8Array(32);
+    return sha256(TE.encode(text));
+}
+// ---------------------------------------------------------------------------
+// PDAs
+// ---------------------------------------------------------------------------
+/** The `["pay_config"]` singleton. */
+export async function findPayConfigPda(find, programId) {
+    return find([TE.encode(PAY_CONFIG_SEED)], toBase58(programId, "programId"));
+}
+/** An invoice: `["invoice", payee, id]`. */
+export async function findInvoicePda(find, programId, payee, id) {
+    return find([TE.encode(INVOICE_SEED), toBytes32(payee, "payee"), checkId(id)], toBase58(programId, "programId"));
+}
+/** A merchant grant: `["merchant", payee, delegate]`. */
+export async function findMerchantAuthorityPda(find, programId, payee, delegate) {
+    return find([TE.encode(MERCHANT_AUTHORITY_SEED), toBytes32(payee, "payee"), toBytes32(delegate, "delegate")], toBase58(programId, "programId"));
+}
+/** A name's X1 payment record, `["record", handle, PAY_X1_COIN_TYPE]`, the
+ *  `payee_record` account of a handle-bound invoice (existing or not). */
+export async function findPayeeX1RecordPda(find, programId, handle) {
+    return find([TE.encode("record"), toBytes32(handle, "handle"), u32le(PAY_X1_COIN_TYPE)], toBase58(programId, "programId"));
+}
+/** Associated token account of `owner` for `mint` under `tokenProgram`. */
+export async function findPayTokenAccount(find, owner, mint, tokenProgram) {
+    return find([toBytes32(owner, "owner"), toBytes32(tokenProgram, "tokenProgram"), toBytes32(mint, "mint")], PAY_ASSOCIATED_TOKEN_PROGRAM);
+}
+/** Decode a raw `PayConfig` (discriminator included); null if not one. */
+export function decodePayConfig(data) {
+    if (data.length < PAY_CONFIG_ACCOUNT_LEN || !hasPrefix(data, PAY_CONFIG_ACCOUNT_DISCRIMINATOR))
+        return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return { version: data[8], bump: data[9], feeBps: dv.getUint16(10, true), updatedAt: dv.getBigInt64(12, true) };
+}
+/** Decode a raw `MerchantAuthority` (discriminator included); null if not one. */
+export function decodeMerchantAuthority(data) {
+    if (data.length < MERCHANT_AUTHORITY_ACCOUNT_LEN || !hasPrefix(data, MERCHANT_AUTHORITY_ACCOUNT_DISCRIMINATOR)) {
+        return null;
+    }
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    return {
+        version: data[8],
+        payee: encodeBase58(data.slice(9, 41)),
+        delegate: encodeBase58(data.slice(41, 73)),
+        createdAt: dv.getBigInt64(73, true),
+        bump: data[81],
+    };
+}
+const STATUS_NAMES = ["open", "paid", "cancelled"];
+/**
+ * Decode a raw `Invoice` (discriminator included) in the exact Borsh order
+ * of state.rs: version u8 | payee | creator | id [u8;16] | mint | amount u64 |
+ * expires_at i64 | status u8 | paid_by | paid_at i64 | handle Option<Pubkey>
+ * (1 tag byte, +32 when Some) | memo_hash [u8;32] | rent_payer | bump u8.
+ * `handle` is variable-width, so the fields after it move by 32 bytes when
+ * the invoice is unbound. Null when the bytes are not an `Invoice`.
+ */
+export function decodeInvoice(data) {
+    if (!hasPrefix(data, INVOICE_ACCOUNT_DISCRIMINATOR) || data.length < INVOICE_OFFSETS.handle + 1)
+        return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const pk = (o) => encodeBase58(data.slice(o, o + 32));
+    const statusByte = data[INVOICE_OFFSETS.status];
+    const status = STATUS_NAMES[statusByte];
+    if (status === undefined)
+        return null;
+    const tag = data[INVOICE_OFFSETS.handle];
+    if (tag > 1)
+        return null;
+    let o = INVOICE_OFFSETS.handle + 1;
+    let handle = null;
+    if (tag === 1) {
+        if (data.length < o + 32)
+            return null;
+        handle = pk(o);
+        o += 32;
+    }
+    if (data.length < o + 32 + 32 + 1)
+        return null;
+    const memoHash = data.slice(o, o + 32);
+    const rentPayer = pk(o + 32);
+    const bump = data[o + 64];
+    const mint = pk(INVOICE_OFFSETS.mint);
+    return {
+        version: data[INVOICE_OFFSETS.version],
+        payee: pk(INVOICE_OFFSETS.payee),
+        creator: pk(INVOICE_OFFSETS.creator),
+        id: data.slice(INVOICE_OFFSETS.id, INVOICE_OFFSETS.id + INVOICE_ID_LEN),
+        mint,
+        isNative: mint === INVOICE_NATIVE_MINT,
+        amount: dv.getBigUint64(INVOICE_OFFSETS.amount, true),
+        expiresAt: dv.getBigInt64(INVOICE_OFFSETS.expiresAt, true),
+        status,
+        paidBy: pk(INVOICE_OFFSETS.paidBy),
+        paidAt: dv.getBigInt64(INVOICE_OFFSETS.paidAt, true),
+        handle,
+        memoHash,
+        rentPayer,
+        bump,
+    };
+}
+/** Borsh-encode an {@link Invoice} exactly as the program stores it (the
+ *  inverse of {@link decodeInvoice}, padded to the allocated length). Useful
+ *  for tests, fixtures and mocks. */
+export function encodeInvoice(inv) {
+    const status = STATUS_NAMES.indexOf(inv.status);
+    if (status < 0)
+        throw new Error("bad status");
+    const body = concat(INVOICE_ACCOUNT_DISCRIMINATOR, Uint8Array.of(inv.version), toBytes32(inv.payee, "payee"), toBytes32(inv.creator, "creator"), checkId(inv.id), toBytes32(inv.mint, "mint"), u64le(inv.amount), i64le(inv.expiresAt), Uint8Array.of(status), toBytes32(inv.paidBy, "paidBy"), i64le(inv.paidAt), inv.handle === null ? Uint8Array.of(0) : concat(Uint8Array.of(1), toBytes32(inv.handle, "handle")), inv.memoHash, toBytes32(inv.rentPayer, "rentPayer"), Uint8Array.of(inv.bump));
+    const out = new Uint8Array(Math.max(INVOICE_ACCOUNT_LEN, body.length));
+    out.set(body);
+    return out;
+}
+function toSecs(n) {
+    return typeof n === "bigint" ? n : BigInt(Math.floor(n));
+}
+/** Whether the invoice is past a non-zero expiry at `nowSecs` (the program's
+ *  rule: payable while `now < expires_at`). */
+export function isInvoiceExpired(invoice, nowSecs) {
+    return invoice.expiresAt !== 0n && toSecs(nowSecs) >= invoice.expiresAt;
+}
+/** The status a person should see at `nowSecs`. */
+export function invoiceStatusLabel(invoice, nowSecs) {
+    if (invoice.status === "paid")
+        return "Paid";
+    if (invoice.status === "cancelled")
+        return "Cancelled";
+    return isInvoiceExpired(invoice, nowSecs) ? "Expired" : "Open";
+}
+/** Whether `pay_invoice` would accept the invoice at `nowSecs` (Open and not
+ *  expired). Chain time can lag the local clock, so treat this as a hint. */
+export function isInvoicePayable(invoice, nowSecs) {
+    return invoice.status === "open" && !isInvoiceExpired(invoice, nowSecs);
+}
+/**
+ * Read and decode an Invoice account. Null when the account does not exist.
+ * Throws when it exists but is not an Invoice, or (with `programId`) is not
+ * owned by the registry program.
+ */
+export async function fetchInvoice(rpc, address, opts = {}) {
+    const addr = toBase58(address, "address");
+    const res = (await rpc("getAccountInfo", [addr, { encoding: "base64", commitment: opts.commitment ?? "confirmed" }]));
+    const v = res?.value;
+    if (!v)
+        return null;
+    if (opts.programId !== undefined && v.owner !== toBase58(opts.programId, "programId")) {
+        throw new Error("account is not owned by the registry program");
+    }
+    const bin = atob(v.data[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    const invoice = decodeInvoice(data);
+    if (!invoice)
+        throw new Error("account is not an X1ID invoice");
+    return { address: addr, invoice, lamports: BigInt(v.lamports) };
+}
+/** Read the live fee rate: the `PayConfig`'s `fee_bps` (clamped to the cap),
+ *  or 0 when the account does not exist, exactly as `pay_invoice` resolves it. */
+export async function fetchPayFeeBps(rpc, payConfig, programId) {
+    const res = (await rpc("getAccountInfo", [
+        toBase58(payConfig, "payConfig"),
+        { encoding: "base64", commitment: "confirmed" },
+    ]));
+    const v = res?.value;
+    if (!v || v.owner !== toBase58(programId, "programId"))
+        return 0;
+    const bin = atob(v.data[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    const c = decodePayConfig(data);
+    if (!c)
+        throw new Error("pay_config account is not a valid PayConfig");
+    return Math.min(c.feeBps, PAY_FEE_BPS_MAX);
+}
+function bindingRemaining(b) {
+    const out = [];
+    if (b.pnftTokenAccount !== undefined)
+        out.push(key(b.pnftTokenAccount, "pnftTokenAccount", false, false));
+    if (b.namespace !== undefined)
+        out.push(key(b.namespace, "namespace", false, false));
+    return out;
+}
+/** `set_pay_config(fee_bps)`. Accounts (`SetPayConfig`): admin(s,w), config,
+ *  pay_config(w), system_program. */
+export function buildSetPayConfigIx(p) {
+    if (!Number.isInteger(p.feeBps) || p.feeBps < 0 || p.feeBps > PAY_FEE_BPS_MAX) {
+        throw new Error(`feeBps must be an integer between 0 and ${PAY_FEE_BPS_MAX}`);
+    }
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            key(p.admin, "admin", true, true),
+            key(p.config, "config", false, false),
+            key(p.payConfig, "payConfig", false, true),
+            key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ],
+        data: concat(SET_PAY_CONFIG_DISCRIMINATOR, u16le(p.feeBps)),
+    };
+}
+/** The Borsh arguments of `create_invoice` (after the discriminator). */
+export function encodeCreateInvoiceArgs(a) {
+    if (a.memoHash.length !== 32)
+        throw new Error("memoHash must be exactly 32 bytes");
+    return concat(checkId(a.id), toBytes32(a.mint, "mint"), u64le(a.amount), i64le(a.expiresAt), a.memoHash, Uint8Array.of(a.bindHandle ? 1 : 0));
+}
+/**
+ * `create_invoice(id, mint, amount, expires_at, memo_hash, bind_handle)`.
+ * Accounts (`CreateInvoice`): creator(s), rent_payer(s,w), payee, config,
+ * invoice(w), system_program, then the optionals merchant_authority, handle,
+ * payee_record (program id = "None" where a later one is used), then the
+ * binding's remaining accounts.
+ */
+export function buildCreateInvoiceIx(p) {
+    const programId = toBase58(p.programId, "programId");
+    const creator = toBase58(p.creator, "creator");
+    const payee = p.payee !== undefined ? toBase58(p.payee, "payee") : creator;
+    const rentPayer = p.rentPayer !== undefined ? toBase58(p.rentPayer, "rentPayer") : creator;
+    if (typeof p.amount !== "bigint" || p.amount <= 0n || p.amount > U64_MAX) {
+        throw new Error("amount must be a u64 bigint greater than zero");
+    }
+    const expiresAt = p.expiresAt ?? 0n;
+    if (typeof expiresAt !== "bigint" || expiresAt < 0n || expiresAt > I64_MAX) {
+        throw new Error("expiresAt must be a non-negative i64 bigint (0n = never)");
+    }
+    if (creator !== payee && p.merchantAuthority === undefined) {
+        throw new Error("a creator other than the payee needs merchantAuthority (the payee's grant)");
+    }
+    const none = () => ({ pubkey: programId, isSigner: false, isWritable: false });
+    const keys = [
+        key(creator, "creator", true, false),
+        key(rentPayer, "rentPayer", true, true),
+        key(payee, "payee", false, false),
+        key(p.config, "config", false, false),
+        key(p.invoice, "invoice", false, true),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ];
+    if (p.merchantAuthority !== undefined || p.bindHandle !== undefined) {
+        keys.push(p.merchantAuthority !== undefined ? key(p.merchantAuthority, "merchantAuthority", false, false) : none());
+    }
+    if (p.bindHandle !== undefined) {
+        keys.push(key(p.bindHandle.handle, "handle", false, false));
+        keys.push(key(p.bindHandle.payeeRecord, "payeeRecord", false, false));
+        keys.push(...bindingRemaining(p.bindHandle));
+    }
+    return {
+        programId,
+        keys,
+        data: concat(CREATE_INVOICE_DISCRIMINATOR, encodeCreateInvoiceArgs({
+            id: p.id,
+            mint: p.mint ?? INVOICE_NATIVE_MINT,
+            amount: p.amount,
+            expiresAt,
+            memoHash: p.memoHash ?? new Uint8Array(32),
+            bindHandle: p.bindHandle !== undefined,
+        })),
+    };
+}
+/** The Borsh arguments of `pay_invoice` (after the discriminator):
+ *  `expected_amount: u64`, `expected_mint: Pubkey`. */
+export function encodePayInvoiceArgs(a) {
+    if (typeof a.expectedAmount !== "bigint" || a.expectedAmount <= 0n || a.expectedAmount > U64_MAX) {
+        throw new Error("expectedAmount must be a u64 bigint greater than zero");
+    }
+    if (a.expectedMint === undefined || a.expectedMint === null) {
+        throw new Error(`expectedMint is required (${INVOICE_NATIVE_MINT} for native XNT)`);
+    }
+    return concat(u64le(a.expectedAmount), toBytes32(a.expectedMint, "expectedMint"));
+}
+/**
+ * `pay_invoice(expected_amount, expected_mint)`. The two arguments pin the
+ * terms the payer reviewed: an Open invoice's PDA can be re-initialised with
+ * new terms (cancel + close + create of the same id, in one transaction) after
+ * the payer signed, and the program then refuses with `InvoiceTermsChanged`
+ * instead of charging the new amount (Sentinel x1p-007-01). A
+ * discriminator-only payload (SDK < 0.26) fails `InstructionDidNotDeserialize`.
+ *
+ * Accounts (`PayInvoice`): payer(s,w), invoice(w), payee(w),
+ * config, treasury(w), pay_config, system_program, then eight optionals:
+ * handle, payee_record, mint, payer_token_account(w), payee_token_account(w),
+ * treasury_token_account(w), token_program, associated_token_program; then
+ * the binding's remaining accounts. Remaining accounts start after ALL eight
+ * optional slots, so a native payment with a binding proof fills the six SPL
+ * slots with the "None" placeholder.
+ */
+export function buildPayInvoiceIx(p) {
+    const programId = toBase58(p.programId, "programId");
+    const args = encodePayInvoiceArgs({ expectedAmount: p.expectedAmount, expectedMint: p.expectedMint });
+    const native = toBase58(p.expectedMint, "expectedMint") === INVOICE_NATIVE_MINT;
+    if (native && p.spl !== undefined)
+        throw new Error("a native (XNT) invoice takes no SPL accounts");
+    if (!native) {
+        if (p.spl === undefined)
+            throw new Error("an SPL invoice needs its SPL accounts (spl)");
+        if (toBase58(p.spl.mint, "spl.mint") !== toBase58(p.expectedMint, "expectedMint")) {
+            throw new Error("spl.mint must equal expectedMint");
+        }
+    }
+    const none = () => ({ pubkey: programId, isSigner: false, isWritable: false });
+    const keys = [
+        key(p.payer, "payer", true, true),
+        key(p.invoice, "invoice", false, true),
+        key(p.payee, "payee", false, true),
+        key(p.config, "config", false, false),
+        key(p.treasury, "treasury", false, true),
+        key(p.payConfig, "payConfig", false, false),
+        key(SYSTEM_PROGRAM, "systemProgram", false, false),
+    ];
+    const remaining = p.binding !== undefined ? bindingRemaining(p.binding) : [];
+    if (p.binding !== undefined || p.spl !== undefined) {
+        if (p.binding !== undefined) {
+            keys.push(key(p.binding.handle, "handle", false, false));
+            keys.push(key(p.binding.payeeRecord, "payeeRecord", false, false));
+        }
+        else {
+            keys.push(none(), none());
+        }
+    }
+    if (p.spl !== undefined) {
+        keys.push(key(p.spl.mint, "mint", false, false), key(p.spl.payerTokenAccount, "payerTokenAccount", false, true), key(p.spl.payeeTokenAccount, "payeeTokenAccount", false, true), key(p.spl.treasuryTokenAccount, "treasuryTokenAccount", false, true), key(p.spl.tokenProgram, "tokenProgram", false, false), key(PAY_ASSOCIATED_TOKEN_PROGRAM, "associatedTokenProgram", false, false));
+    }
+    else if (remaining.length > 0) {
+        for (let i = 0; i < 6; i++)
+            keys.push(none());
+    }
+    keys.push(...remaining);
+    return { programId, keys, data: concat(PAY_INVOICE_DISCRIMINATOR, args) };
+}
+/** `cancel_invoice()`. Accounts (`CancelInvoice`): signer(s), invoice(w),
+ *  then the optional merchant_authority. */
+export function buildCancelInvoiceIx(p) {
+    const keys = [key(p.signer, "signer", true, false), key(p.invoice, "invoice", false, true)];
+    if (p.merchantAuthority !== undefined)
+        keys.push(key(p.merchantAuthority, "merchantAuthority", false, false));
+    return { programId: toBase58(p.programId, "programId"), keys, data: CANCEL_INVOICE_DISCRIMINATOR.slice() };
+}
+/** `close_invoice()`. Accounts (`CloseInvoice`): signer(s), invoice(w),
+ *  rent_payer(w). */
+export function buildCloseInvoiceIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            key(p.signer, "signer", true, false),
+            key(p.invoice, "invoice", false, true),
+            key(p.rentPayer, "rentPayer", false, true),
+        ],
+        data: CLOSE_INVOICE_DISCRIMINATOR.slice(),
+    };
+}
+/** `create_merchant_authority(delegate)`. Accounts
+ *  (`CreateMerchantAuthority`): payee(s,w), merchant_authority(w), system_program. */
+export function buildCreateMerchantAuthorityIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [
+            key(p.payee, "payee", true, true),
+            key(p.merchantAuthority, "merchantAuthority", false, true),
+            key(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ],
+        data: concat(CREATE_MERCHANT_AUTHORITY_DISCRIMINATOR, toBytes32(p.delegate, "delegate")),
+    };
+}
+/** `revoke_merchant_authority()`. Accounts (`RevokeMerchantAuthority`):
+ *  payee(s,w), merchant_authority(w). */
+export function buildRevokeMerchantAuthorityIx(p) {
+    return {
+        programId: toBase58(p.programId, "programId"),
+        keys: [key(p.payee, "payee", true, true), key(p.merchantAuthority, "merchantAuthority", false, true)],
+        data: REVOKE_MERCHANT_AUTHORITY_DISCRIMINATOR.slice(),
+    };
+}
+// ---------------------------------------------------------------------------
+// error helpers
+// ---------------------------------------------------------------------------
+/** Plain-language sentence for a Pay program error code, or null. */
+export function payErrorMessage(code) {
+    switch (code) {
+        case 6121: return "The fee is above the program's 1% cap.";
+        case 6122: return "The fee config account is not the canonical one.";
+        case 6123: return "An invoice amount must be greater than zero.";
+        case 6124: return "The expiry must be in the future (or none).";
+        case 6125: return "Only the payee or one of their authorized merchant keys can do this.";
+        case 6126: return "This wallet is not the payment address of that name.";
+        case 6127: return "The name on this invoice no longer pays to its payee, so it can't be paid.";
+        case 6128: return "The name accounts don't match this invoice.";
+        case 6129: return "This invoice is no longer open (it was paid or cancelled).";
+        case 6130: return "This invoice has expired.";
+        case 6131: return "The token or token accounts don't match this invoice.";
+        case 6132: return "The payee account doesn't match this invoice.";
+        case 6133: return "The treasury account doesn't match the registry.";
+        case 6134: return "Only the payee or whoever paid the rent can close this invoice.";
+        case 6135: return "This invoice is still open and not expired, so it can't be closed yet.";
+        case 6136: return "This invoice's amount or token changed after you reviewed it. Nothing was charged; reload it before paying.";
+        default: return null;
+    }
+}
+/**
+ * The instruction to SIMULATE (never send) to learn whether the deployed
+ * program has Pay: `pay_invoice` with no accounts and all-zero arguments. A
+ * Pay-enabled program recognizes the discriminator, decodes the arguments and
+ * fails account validation (3005 `AccountNotEnoughKeys`); an older one answers
+ * `InstructionFallbackNotFound` (101). Read the simulation's `err` with
+ * {@link classifyPayProbe}.
+ *
+ * Simulate it with `sigVerify: false`, `replaceRecentBlockhash: true` and a
+ * fee payer that EXISTS and is SYSTEM-owned (the connected wallet, or a fixed
+ * funded system account). A program-owned fee payer such as a multisig
+ * treasury fails the whole transaction (`InvalidAccountForFee`) before the
+ * probe runs, which says nothing about Pay.
+ */
+export function buildPayProbeIx(programId) {
+    return {
+        programId: toBase58(programId, "programId"),
+        keys: [],
+        data: concat(PAY_INVOICE_DISCRIMINATOR, new Uint8Array(8 + 32)),
+    };
+}
+/**
+ * Classify a probe simulation's `value.err` (probe at `probeIndex`). Only an
+ * `InstructionError` AT the probe index is evidence: `Custom 101` =
+ * "not-deployed", any other custom code = "live". Everything else is
+ * "unknown".
+ */
+export function classifyPayProbe(err, probeIndex) {
+    if (!err || typeof err !== "object")
+        return "unknown";
+    const ie = err.InstructionError;
+    if (!Array.isArray(ie) || ie.length !== 2 || ie[0] !== probeIndex)
+        return "unknown";
+    const detail = ie[1];
+    if (typeof detail === "object" && detail !== null && typeof detail.Custom === "number") {
+        return detail.Custom === PAY_NOT_DEPLOYED_ERROR ? "not-deployed" : "live";
+    }
+    return "unknown";
+}
+/**
+ * @deprecated Two-state view of {@link classifyPayProbe}: `true` only for
+ * "live". It cannot tell "not deployed" from "the simulation said nothing"
+ * (e.g. a program-owned fee payer); use {@link classifyPayProbe}.
+ */
+export function interpretPayProbe(err, probeIndex) {
+    return classifyPayProbe(err, probeIndex) === "live";
+}
+/** Whether a simulation / transaction error says the program does not know
+ *  Pay instructions yet (Anchor `InstructionFallbackNotFound`, code 101). */
+export function isPayNotDeployedError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const ie = err.InstructionError;
+    if (!Array.isArray(ie) || ie.length !== 2)
+        return false;
+    const detail = ie[1];
+    return typeof detail === "object" && detail !== null && detail.Custom === PAY_NOT_DEPLOYED_ERROR;
+}
+function toExpectedAmount(v) {
+    let n;
+    if (typeof v === "bigint")
+        n = v;
+    else if (typeof v === "number") {
+        if (!Number.isSafeInteger(v))
+            throw new Error("amount must be an integer number of base units (use a bigint for large values)");
+        n = BigInt(v);
+    }
+    else if (typeof v === "string" && /^[0-9]{1,20}$/.test(v))
+        n = BigInt(v);
+    else
+        throw new Error("amount must be base units: a bigint, a safe integer or a decimal string");
+    if (n <= 0n || n > U64_MAX)
+        throw new Error("amount must be a u64 greater than zero");
+    return n;
+}
+/**
+ * MERCHANT SERVER: is `invoice` paid, on chain, with exactly the terms you
+ * expect? This is the check that releases goods. A checkout widget result,
+ * a redirect or a webhook is only a hint to call this.
+ *
+ * Reads the Invoice account (one `getAccountInfo`) and returns `paid: true`
+ * only when ALL hold: the account is owned by the registry program, decodes
+ * as an Invoice, its payee, mint, amount (and `id`, when given) equal what you
+ * expect, and its status is Paid. The program moved the funds payer → payee in
+ * the same instruction that set Paid, so Paid means paid.
+ *
+ * Pass the invoice address and terms from YOUR database (the ones you used to
+ * create the invoice), never from the browser. Mark the order fulfilled once
+ * and idempotently: after payment the invoice can be closed, and a closed
+ * invoice reads as `not-found`.
+ *
+ * `rpc` is an RPC URL or an {@link RpcFn}. Throws on RPC/transport errors
+ * (retry) and on malformed arguments; every on-chain answer is a result.
+ */
+export async function verifyInvoicePaid(rpc, invoice, expect) {
+    const call = typeof rpc === "string" ? makeAccountReader(rpc).rpc : rpc;
+    const address = toBase58(invoice, "invoice");
+    const programId = toBase58(expect.programId ?? DEFAULT_HANDLE_PROGRAM, "programId");
+    const payee = toBase58(expect.payee, "payee");
+    const mint = toBase58(expect.mint ?? INVOICE_NATIVE_MINT, "mint");
+    const amount = toExpectedAmount(expect.amount);
+    let id = null;
+    if (expect.id !== undefined) {
+        id = typeof expect.id === "string" ? invoiceIdFromHex(expect.id) : checkId(expect.id);
+        if (!id)
+            throw new Error("id must be 16 bytes or 32 hex characters");
+    }
+    const commitment = expect.commitment ?? "confirmed";
+    if (commitment !== "confirmed" && commitment !== "finalized")
+        throw new Error('commitment must be "confirmed" or "finalized"');
+    const res = (await call("getAccountInfo", [address, { encoding: "base64", commitment }]));
+    const v = res?.value;
+    const fail = (reason, status) => status === undefined ? { paid: false, invoice: address, reason } : { paid: false, invoice: address, reason, status };
+    if (!v)
+        return fail("not-found");
+    if (v.owner !== programId)
+        return fail("wrong-program");
+    const raw = v.data;
+    if (!Array.isArray(raw) || raw[1] !== "base64" || typeof raw[0] !== "string")
+        return fail("not-invoice");
+    const bin = atob(raw[0]);
+    const data = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        data[i] = bin.charCodeAt(i);
+    const inv = decodeInvoice(data);
+    if (!inv)
+        return fail("not-invoice");
+    if (inv.payee !== payee)
+        return fail("wrong-payee", inv.status);
+    if (inv.mint !== mint)
+        return fail("wrong-mint", inv.status);
+    if (inv.amount !== amount)
+        return fail("wrong-amount", inv.status);
+    if (id && !id.every((b, i) => b === inv.id[i]))
+        return fail("wrong-id", inv.status);
+    if (inv.status !== "paid")
+        return fail("not-paid", inv.status);
+    return { paid: true, invoice: address, paidBy: inv.paidBy, paidAt: inv.paidAt, amount: inv.amount, mint: inv.mint, payee: inv.payee };
+}