@x1id/resolve 0.23.0 → 0.43.0

package/dist/pay.d.ts

@@ -0,0 +1,513 @@
+/**
+ * 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 type { AddressLike, BuiltInstruction } from "./delegate.js";
+import { type RpcFn } from "./accounts.js";
+import type { PdaFinder } from "./namespacePricing.js";
+/** Hard cap on the Pay protocol fee in basis points (1%). */
+export declare const PAY_FEE_BPS_MAX = 100;
+/** The X1 record slot a name's payment address is read from. */
+export declare const PAY_X1_COIN_TYPE = 5010000;
+/** `Invoice.mint` for native XNT (`Pubkey::default()`). */
+export declare const INVOICE_NATIVE_MINT = "11111111111111111111111111111111";
+/** Length of an invoice id (`[u8; 16]`). */
+export declare const INVOICE_ID_LEN = 16;
+export declare const PAY_CONFIG_SEED = "pay_config";
+export declare const INVOICE_SEED = "invoice";
+export declare const MERCHANT_AUTHORITY_SEED = "merchant";
+/** Allocated size of each account (8-byte discriminator + `INIT_SPACE`). */
+export declare const PAY_CONFIG_ACCOUNT_LEN: number;
+export declare const INVOICE_ACCOUNT_LEN: number;
+export declare const MERCHANT_AUTHORITY_ACCOUNT_LEN: number;
+/** Byte offsets inside a raw `Invoice` account, for `getProgramAccounts`
+ *  `memcmp` filters. Only fields before the variable-width `handle` are fixed. */
+export declare const INVOICE_OFFSETS: {
+    readonly version: 8;
+    readonly payee: 9;
+    readonly creator: 41;
+    readonly id: 73;
+    readonly mint: 89;
+    readonly amount: 121;
+    readonly expiresAt: 129;
+    readonly status: 137;
+    readonly paidBy: 138;
+    readonly paidAt: 170;
+    readonly handle: 178;
+};
+/** `sha256("global:set_pay_config")[..8]`. */
+export declare const SET_PAY_CONFIG_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:create_invoice")[..8]`. */
+export declare const CREATE_INVOICE_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:pay_invoice")[..8]`. */
+export declare const PAY_INVOICE_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:cancel_invoice")[..8]`. */
+export declare const CANCEL_INVOICE_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:close_invoice")[..8]`. */
+export declare const CLOSE_INVOICE_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:create_merchant_authority")[..8]`. */
+export declare const CREATE_MERCHANT_AUTHORITY_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:revoke_merchant_authority")[..8]`. */
+export declare const REVOKE_MERCHANT_AUTHORITY_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:Invoice")[..8]`. */
+export declare const INVOICE_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:PayConfig")[..8]`. */
+export declare const PAY_CONFIG_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:MerchantAuthority")[..8]`. */
+export declare const MERCHANT_AUTHORITY_ACCOUNT_DISCRIMINATOR: Uint8Array;
+/** 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 declare const PAY_ERRORS: {
+    readonly PayFeeAboveMax: 6121;
+    readonly PayConfigMismatch: 6122;
+    readonly InvoiceAmountZero: 6123;
+    readonly InvoiceExpiryInPast: 6124;
+    readonly NotMerchantDelegate: 6125;
+    readonly PayeeNotNamePaymentAddress: 6126;
+    readonly PayeeNoLongerHoldsName: 6127;
+    readonly InvoiceHandleMismatch: 6128;
+    readonly InvoiceNotOpen: 6129;
+    readonly InvoiceExpired: 6130;
+    readonly InvoiceMintMismatch: 6131;
+    readonly InvoicePayeeMismatch: 6132;
+    readonly InvoiceTreasuryMismatch: 6133;
+    readonly NotInvoiceCloser: 6134;
+    readonly InvoiceStillOpen: 6135;
+    readonly InvoiceTermsChanged: 6136;
+};
+/** Anchor's `InstructionFallbackNotFound`: the deployed program predates Pay. */
+export declare const PAY_NOT_DEPLOYED_ERROR = 101;
+/** `Invoice.status` as stored (Borsh enum index). */
+export declare const INVOICE_STATUS: {
+    readonly Open: 0;
+    readonly Paid: 1;
+    readonly Cancelled: 2;
+};
+export type InvoiceStatus = "open" | "paid" | "cancelled";
+/** 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 declare function payFee(amount: bigint, feeBps: number): bigint;
+/** The split of one payment: what the payee and the treasury receive. */
+export interface PaySplit {
+    readonly amount: bigint;
+    readonly fee: bigint;
+    readonly payeeReceives: bigint;
+}
+/** {@link payFee} as a full split. */
+export declare function paySplit(amount: bigint, feeBps: number): PaySplit;
+/** 16 fresh random bytes for a new invoice id (CSPRNG). */
+export declare function newInvoiceId(): Uint8Array;
+/** Lowercase hex of an invoice id (the form used in links). */
+export declare function invoiceIdToHex(id: Uint8Array): string;
+/** Parse a 32-character hex invoice id; null when malformed. */
+export declare function invoiceIdFromHex(hex: string): Uint8Array | null;
+/** `memo_hash` for an off-chain description: sha256 of its UTF-8 bytes. An
+ *  empty description hashes to all zeros (no memo). */
+export declare function invoiceMemoHash(text: string): Uint8Array;
+/** The `["pay_config"]` singleton. */
+export declare function findPayConfigPda(find: PdaFinder, programId: AddressLike): Promise<string>;
+/** An invoice: `["invoice", payee, id]`. */
+export declare function findInvoicePda(find: PdaFinder, programId: AddressLike, payee: AddressLike, id: Uint8Array): Promise<string>;
+/** A merchant grant: `["merchant", payee, delegate]`. */
+export declare function findMerchantAuthorityPda(find: PdaFinder, programId: AddressLike, payee: AddressLike, delegate: AddressLike): Promise<string>;
+/** 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 declare function findPayeeX1RecordPda(find: PdaFinder, programId: AddressLike, handle: AddressLike): Promise<string>;
+/** Associated token account of `owner` for `mint` under `tokenProgram`. */
+export declare function findPayTokenAccount(find: PdaFinder, owner: AddressLike, mint: AddressLike, tokenProgram: AddressLike): Promise<string>;
+/** Decoded `PayConfig`. */
+export interface PayConfig {
+    readonly version: number;
+    readonly bump: number;
+    readonly feeBps: number;
+    readonly updatedAt: bigint;
+}
+/** Decode a raw `PayConfig` (discriminator included); null if not one. */
+export declare function decodePayConfig(data: Uint8Array): PayConfig | null;
+/** Decoded `MerchantAuthority`. */
+export interface MerchantAuthority {
+    readonly version: number;
+    readonly payee: string;
+    readonly delegate: string;
+    readonly createdAt: bigint;
+    readonly bump: number;
+}
+/** Decode a raw `MerchantAuthority` (discriminator included); null if not one. */
+export declare function decodeMerchantAuthority(data: Uint8Array): MerchantAuthority | null;
+/** Decoded `Invoice`. Addresses are base58; `mint === INVOICE_NATIVE_MINT`
+ *  means native XNT. */
+export interface Invoice {
+    readonly version: number;
+    readonly payee: string;
+    readonly creator: string;
+    readonly id: Uint8Array;
+    /** {@link INVOICE_NATIVE_MINT} for XNT, else the SPL mint. */
+    readonly mint: string;
+    readonly isNative: boolean;
+    readonly amount: bigint;
+    /** Unix seconds; 0n = never expires. */
+    readonly expiresAt: bigint;
+    readonly status: InvoiceStatus;
+    /** Set once Paid (the all-ones address before). */
+    readonly paidBy: string;
+    readonly paidAt: bigint;
+    /** The bound `Handle` account, or null. */
+    readonly handle: string | null;
+    readonly memoHash: Uint8Array;
+    readonly rentPayer: string;
+    readonly bump: number;
+}
+/**
+ * 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 declare function decodeInvoice(data: Uint8Array): Invoice | null;
+/** 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 declare function encodeInvoice(inv: Omit<Invoice, "isNative">): Uint8Array;
+/** "Open" / "Paid" / "Cancelled" / "Expired" (an Open invoice at or after its
+ *  non-zero `expiresAt`). */
+export type InvoiceStatusLabel = "Open" | "Paid" | "Cancelled" | "Expired";
+/** Whether the invoice is past a non-zero expiry at `nowSecs` (the program's
+ *  rule: payable while `now < expires_at`). */
+export declare function isInvoiceExpired(invoice: Pick<Invoice, "expiresAt">, nowSecs: bigint | number): boolean;
+/** The status a person should see at `nowSecs`. */
+export declare function invoiceStatusLabel(invoice: Pick<Invoice, "status" | "expiresAt">, nowSecs: bigint | number): InvoiceStatusLabel;
+/** 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 declare function isInvoicePayable(invoice: Pick<Invoice, "status" | "expiresAt">, nowSecs: bigint | number): boolean;
+/** An invoice read from chain. */
+export interface FetchedInvoice {
+    readonly address: string;
+    readonly invoice: Invoice;
+    /** The account's lamports (its rent). */
+    readonly lamports: bigint;
+}
+/**
+ * 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 declare function fetchInvoice(rpc: RpcFn, address: AddressLike, opts?: {
+    readonly programId?: AddressLike;
+    readonly commitment?: string;
+}): Promise<FetchedInvoice | null>;
+/** 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 declare function fetchPayFeeBps(rpc: RpcFn, payConfig: AddressLike, programId: AddressLike): Promise<number>;
+/**
+ * The extra accounts a handle-bound invoice needs. `handle` and
+ * `payeeRecord` fill the two optional slots; the rest go to
+ * `remaining_accounts` in the program's order: the payee's pNFT token account
+ * first (tokenized names), then the `Namespace` (scoped names).
+ */
+export interface InvoiceHandleBinding {
+    /** The `Handle` PDA. */
+    readonly handle: AddressLike;
+    /** {@link findPayeeX1RecordPda}(handle), whether it exists or not. */
+    readonly payeeRecord: AddressLike;
+    /** Tokenized name: the payee's associated token account for the pNFT mint. */
+    readonly pnftTokenAccount?: AddressLike;
+    /** Scoped name (`alice.pepe`): the `["namespace", label]` account. */
+    readonly namespace?: AddressLike;
+}
+export interface SetPayConfigParams {
+    readonly programId: AddressLike;
+    /** `Config.admin` (signer, pays rent on first set). */
+    readonly admin: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** `["pay_config"]` ({@link findPayConfigPda}). */
+    readonly payConfig: AddressLike;
+    /** 0..={@link PAY_FEE_BPS_MAX}. */
+    readonly feeBps: number;
+}
+/** `set_pay_config(fee_bps)`. Accounts (`SetPayConfig`): admin(s,w), config,
+ *  pay_config(w), system_program. */
+export declare function buildSetPayConfigIx(p: SetPayConfigParams): BuiltInstruction;
+export interface CreateInvoiceParams {
+    readonly programId: AddressLike;
+    /** Signer: the payee, or a merchant delegate (then pass `merchantAuthority`). */
+    readonly creator: AddressLike;
+    /** Signer that funds the account rent (refunded on close). Default: creator. */
+    readonly rentPayer?: AddressLike;
+    /** Where the funds go. Default: creator. */
+    readonly payee?: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** {@link findInvoicePda}(payee, id). */
+    readonly invoice: AddressLike;
+    /** 16 bytes ({@link newInvoiceId}). */
+    readonly id: Uint8Array;
+    /** SPL mint; omit (or {@link INVOICE_NATIVE_MINT}) for native XNT. */
+    readonly mint?: AddressLike;
+    /** Base units, > 0. */
+    readonly amount: bigint;
+    /** Unix seconds, 0n / omitted = never. */
+    readonly expiresAt?: bigint;
+    /** 32 bytes ({@link invoiceMemoHash}); default all zeros. */
+    readonly memoHash?: Uint8Array;
+    /** `["merchant", payee, creator]`: required when creator != payee. */
+    readonly merchantAuthority?: AddressLike;
+    /** Bind the invoice to the payee's `@name` (`bind_handle = true`). */
+    readonly bindHandle?: InvoiceHandleBinding;
+}
+/** The Borsh arguments of `create_invoice` (after the discriminator). */
+export declare function encodeCreateInvoiceArgs(a: {
+    readonly id: Uint8Array;
+    readonly mint: AddressLike;
+    readonly amount: bigint;
+    readonly expiresAt: bigint;
+    readonly memoHash: Uint8Array;
+    readonly bindHandle: boolean;
+}): Uint8Array;
+/**
+ * `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 declare function buildCreateInvoiceIx(p: CreateInvoiceParams): BuiltInstruction;
+/** The SPL account set of an SPL invoice's payment. */
+export interface PayInvoiceSplAccounts {
+    readonly mint: AddressLike;
+    /** The payer's token account for the mint (debited). */
+    readonly payerTokenAccount: AddressLike;
+    /** The payee's canonical ATA (must exist; create it idempotently first). */
+    readonly payeeTokenAccount: AddressLike;
+    /** `Config.treasury`'s canonical ATA (created by the program if a fee is due). */
+    readonly treasuryTokenAccount: AddressLike;
+    /** The mint's owner: SPL Token or Token-2022. */
+    readonly tokenProgram: AddressLike;
+}
+export interface PayInvoiceParams {
+    readonly programId: AddressLike;
+    /** Signer; pays exactly the invoice amount. */
+    readonly payer: AddressLike;
+    readonly invoice: AddressLike;
+    /** `Invoice.payee`. */
+    readonly payee: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** `Config.treasury`. */
+    readonly treasury: AddressLike;
+    /** `["pay_config"]`, initialized or not. */
+    readonly payConfig: AddressLike;
+    /** REQUIRED: the `Invoice.amount` (base units) the payer reviewed. The
+     *  program refuses the payment (`InvoiceTermsChanged`, 6136) if the invoice
+     *  holds any other amount when the transaction executes. Pass the amount
+     *  you DISPLAYED, never a value re-read after the user confirmed. */
+    readonly expectedAmount: bigint;
+    /** REQUIRED: the `Invoice.mint` the payer reviewed
+     *  ({@link INVOICE_NATIVE_MINT} for native XNT). Same rule as
+     *  `expectedAmount`. */
+    readonly expectedMint: AddressLike;
+    /** Required for a handle-bound invoice (`Invoice.handle`). */
+    readonly binding?: InvoiceHandleBinding;
+    /** Required for an SPL invoice. */
+    readonly spl?: PayInvoiceSplAccounts;
+}
+/** The Borsh arguments of `pay_invoice` (after the discriminator):
+ *  `expected_amount: u64`, `expected_mint: Pubkey`. */
+export declare function encodePayInvoiceArgs(a: {
+    readonly expectedAmount: bigint;
+    readonly expectedMint: AddressLike;
+}): Uint8Array;
+/**
+ * `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 declare function buildPayInvoiceIx(p: PayInvoiceParams): BuiltInstruction;
+export interface CancelInvoiceParams {
+    readonly programId: AddressLike;
+    /** The payee, or the invoice's creator (a delegate: pass `merchantAuthority`). */
+    readonly signer: AddressLike;
+    readonly invoice: AddressLike;
+    /** `["merchant", payee, signer]`, needed when a delegate cancels. */
+    readonly merchantAuthority?: AddressLike;
+}
+/** `cancel_invoice()`. Accounts (`CancelInvoice`): signer(s), invoice(w),
+ *  then the optional merchant_authority. */
+export declare function buildCancelInvoiceIx(p: CancelInvoiceParams): BuiltInstruction;
+export interface CloseInvoiceParams {
+    readonly programId: AddressLike;
+    /** The payee or the rent payer. */
+    readonly signer: AddressLike;
+    readonly invoice: AddressLike;
+    /** `Invoice.rentPayer`: receives the refund. */
+    readonly rentPayer: AddressLike;
+}
+/** `close_invoice()`. Accounts (`CloseInvoice`): signer(s), invoice(w),
+ *  rent_payer(w). */
+export declare function buildCloseInvoiceIx(p: CloseInvoiceParams): BuiltInstruction;
+export interface CreateMerchantAuthorityParams {
+    readonly programId: AddressLike;
+    /** Signer; pays the rent. */
+    readonly payee: AddressLike;
+    /** The key allowed to create and cancel invoices for `payee`. */
+    readonly delegate: AddressLike;
+    /** {@link findMerchantAuthorityPda}(payee, delegate). */
+    readonly merchantAuthority: AddressLike;
+}
+/** `create_merchant_authority(delegate)`. Accounts
+ *  (`CreateMerchantAuthority`): payee(s,w), merchant_authority(w), system_program. */
+export declare function buildCreateMerchantAuthorityIx(p: CreateMerchantAuthorityParams): BuiltInstruction;
+export interface RevokeMerchantAuthorityParams {
+    readonly programId: AddressLike;
+    /** Signer; receives the rent back. */
+    readonly payee: AddressLike;
+    readonly merchantAuthority: AddressLike;
+}
+/** `revoke_merchant_authority()`. Accounts (`RevokeMerchantAuthority`):
+ *  payee(s,w), merchant_authority(w). */
+export declare function buildRevokeMerchantAuthorityIx(p: RevokeMerchantAuthorityParams): BuiltInstruction;
+/** Plain-language sentence for a Pay program error code, or null. */
+export declare function payErrorMessage(code: number): string | 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 declare function buildPayProbeIx(programId: AddressLike): BuiltInstruction;
+/** What a Pay probe simulation says about the deployed program. */
+export type PayProbeResult = 
+/** The program recognized `pay_invoice` (any custom error but 101 from the probe). */
+"live"
+/** The probe itself failed with `InstructionFallbackNotFound` (101). */
+ | "not-deployed"
+/** Anything else: a transaction-level error (`InvalidAccountForFee`,
+ *  `AccountNotFound`, `InsufficientFundsForFee`, ...), an error in another
+ *  instruction, an unexpected success, or no answer. Says nothing about Pay:
+ *  never cache it, and let the chain decide at send time. */
+ | "unknown";
+/**
+ * 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 declare function classifyPayProbe(err: unknown, probeIndex: number): PayProbeResult;
+/**
+ * @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 declare function interpretPayProbe(err: unknown, probeIndex: number): boolean;
+/** Whether a simulation / transaction error says the program does not know
+ *  Pay instructions yet (Anchor `InstructionFallbackNotFound`, code 101). */
+export declare function isPayNotDeployedError(err: unknown): boolean;
+/** What the merchant expects the invoice to say: the terms it STORED when it
+ *  created the invoice, never values taken from the buyer's browser. */
+export interface VerifyInvoicePaidExpect {
+    /** The wallet the funds go to. */
+    readonly payee: AddressLike;
+    /** Exact amount in base units (bigint, a safe integer number, or a decimal
+     *  string of base units). */
+    readonly amount: bigint | number | string;
+    /** SPL mint; omit (or {@link INVOICE_NATIVE_MINT}) for native XNT. */
+    readonly mint?: AddressLike;
+    /** The invoice id (16 bytes or 32 hex chars). Recommended: binds the check
+     *  to ONE order, so one paid invoice can never satisfy two orders. */
+    readonly id?: Uint8Array | string;
+    /** The registry program. Default {@link DEFAULT_HANDLE_PROGRAM}. */
+    readonly programId?: AddressLike;
+    /** Default "confirmed". Use "finalized" for high-value goods (a few seconds
+     *  later, but cannot be rolled back). */
+    readonly commitment?: "confirmed" | "finalized";
+}
+export type VerifyInvoicePaidFailure = 
+/** No account at that address (never created, or closed after payment). */
+"not-found"
+/** The account is not owned by the registry program. */
+ | "wrong-program"
+/** The account is not an Invoice. */
+ | "not-invoice" | "wrong-payee" | "wrong-amount" | "wrong-mint" | "wrong-id"
+/** The invoice exists with the right terms but is not Paid (yet). */
+ | "not-paid";
+export type VerifyInvoicePaidResult = {
+    readonly paid: true;
+    readonly invoice: string;
+    readonly paidBy: string;
+    /** Unix seconds (chain clock). */
+    readonly paidAt: bigint;
+    readonly amount: bigint;
+    readonly mint: string;
+    readonly payee: string;
+} | {
+    readonly paid: false;
+    readonly invoice: string;
+    readonly reason: VerifyInvoicePaidFailure;
+    /** The on-chain status when the invoice was readable. */
+    readonly status?: InvoiceStatus;
+};
+/**
+ * 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 declare function verifyInvoicePaid(rpc: RpcFn | string, invoice: AddressLike, expect: VerifyInvoicePaidExpect): Promise<VerifyInvoicePaidResult>;