@x1id/resolve 0.23.0 → 0.44.0

package/dist/textRecords.d.ts

@@ -53,6 +53,25 @@
  * `ParsedHandle`), and a text record is `stale` when EITHER
  * `updated_at < registeredAt` OR `updated_at < recordsClearedAt`.
  *
+ * # `holder_epoch` (H5 / PR #466) — the THIRD staleness anchor
+ *
+ * A native tokenized `buy_handle` stamps ONLY `holder_epoch` (it must not
+ * move `registered_at`), so without it the seller's records — including the
+ * payment-routing `x1.*` keys — stayed live after a sale. The same functions
+ * take the handle's `holderEpoch` (0 if absent) and judge a text record
+ * stale when `updated_at < max(registeredAt, holderEpoch, recordsClearedAt)`
+ * — the on-chain `name_pays_to` rule and the address-record reader's rule.
+ *
+ * # Keys are compared BYTE-EXACT (BOM-preserving decode)
+ *
+ * The program accepts any UTF-8 key of 1..=64 bytes, including one that
+ * starts with a U+FEFF byte-order mark. A default `TextDecoder` STRIPS a
+ * leading BOM, so a key stored as `EF BB BF "x1.shield"` used to read back
+ * as `"x1.shield"` — a record delegate could spoof a routing key. Keys here
+ * are decoded with `ignoreBOM: true`, so the BOM survives into `key` and the
+ * decoded string is equal to a lookup key only when the raw bytes are. Use
+ * {@link findTextRecord} to look up a specific key.
+ *
  * # These records count (#7384)
  *
  * `create_text_record` increments — and `close_text_record` decrements —
@@ -125,13 +144,22 @@ export interface HandleTextRecord {
     readonly updatedAt: bigint;
     /**
      * The rule docs/record-trust.md mandates: this record is only the current
-     * owner's if `updated_at >= handle.registered_at`. A stale record belongs
+     * owner's if `updated_at >= max(handle.registered_at, handle.holder_epoch,
+     * handle.records_cleared_at)`. A stale record belongs
      * to a previous, unrelated owner of the same name: it must never be
      * rendered as this name's website/avatar/social, and only ever offered to
      * the CURRENT owner as something to remove or overwrite.
      */
     readonly stale: boolean;
 }
+/**
+ * Decode a stored KEY: strict UTF-8 with the byte-order mark PRESERVED
+ * (`ignoreBOM: true`). A default decoder silently drops a leading U+FEFF,
+ * which made `EF BB BF "x1.shield"` read back as `"x1.shield"`. With the BOM
+ * kept, `decoded === key` holds exactly when the raw bytes are identical
+ * (UTF-8 is a bijection on valid input). Null when not valid UTF-8.
+ */
+export declare function textKeyFromBytes(keyBytes: Uint8Array): string | null;
 /**
  * Render stored value bytes as text: a STRICT UTF-8 decode, or null when the
  * bytes are not valid UTF-8 (binary values like `contenthash`). Callers
@@ -150,18 +178,34 @@ export declare function textValueToString(value: Uint8Array): string | null;
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
  * caller from the Handle account — it decides `stale`. `recordsClearedAt` is
  * that same Handle's `recordsClearedAt` (0 if never cleared, #8139), a
- * SECOND independent staleness anchor. There is intentionally no overload
- * without either (see the module docs).
+ * SECOND independent staleness anchor. `holderEpoch` is that Handle's
+ * `holderEpoch` (H5, 0 if absent): stale when
+ * `updated_at < max(registeredAt, holderEpoch, recordsClearedAt)`. It
+ * defaults to `0n` only for backward compatibility; every caller that has a
+ * decoded Handle should pass it (a payment-routing reader MUST).
  *
  * Returns null for anything that is not a TextRecord: wrong length, wrong
  * discriminator, lengths that do not fit, or a key that is not valid UTF-8
  * (the program's Borsh `String` guarantees it is, so that is not a
  * TextRecord).
  */
-export declare function decodeTextRecord(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: bigint): HandleTextRecord | null;
+export declare function decodeTextRecord(raw: Uint8Array, account: string, registeredAt: bigint, recordsClearedAt: bigint, holderEpoch?: bigint): HandleTextRecord | null;
 /** The text records the CURRENT owner actually has — `stale` ones excluded.
  *  This is the list to render on a profile and count. */
 export declare function liveTextRecords(records: readonly HandleTextRecord[]): HandleTextRecord[];
+/**
+ * The LIVE record whose stored key bytes are EXACTLY `key`'s UTF-8 bytes, or
+ * undefined. Use this (not `records.find((r) => r.key === key)`) for any key
+ * that routes funds or changes behaviour (`x1.shield`, `x1.pool`, ...).
+ *
+ * Byte-exact by construction: keys are decoded BOM-preserving, so a
+ * `U+FEFF`-prefixed look-alike never equals `key`; the raw bytes are compared
+ * again here as defence in depth. If more than one live record matches
+ * (impossible for well-formed PDAs, since the address is derived from
+ * sha256(key)), it returns undefined: ordering never decides which record
+ * routes.
+ */
+export declare function findTextRecord(records: readonly HandleTextRecord[], key: string): HandleTextRecord | undefined;
 /**
  * Fetch every TextRecord account of a handle — one `getProgramAccounts`
  * call, filtered by the RPC on size (377), the TextRecord discriminator at
@@ -173,12 +217,14 @@ export declare function liveTextRecords(records: readonly HandleTextRecord[]): H
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
  * is no variant of this function without it. `recordsClearedAt` is that same
- * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through,
+ * and `holderEpoch` (H5; defaults to 0n for backward compatibility, but pass
+ * it: a native tokenized sale moves only this anchor).
  * Every record is returned, stale ones flagged, so an owner surface can show
  * what a previous owner left behind; anything that renders a profile takes
  * {@link liveTextRecords}.
  */
-export declare function fetchTextRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint): Promise<HandleTextRecord[]>;
+export declare function fetchTextRecords(rpc: RpcFn, programId: string, handleAccount: string, registeredAt: bigint, recordsClearedAt: bigint, holderEpoch?: bigint): Promise<HandleTextRecord[]>;
 /** The delegate-aware trailing accounts every text-record builder shares —
  *  the exact rules of `delegate.ts`'s module docs. */
 interface RecordEditAuthorityParams {

package/dist/textRecords.js

@@ -53,6 +53,25 @@
  * `ParsedHandle`), and a text record is `stale` when EITHER
  * `updated_at < registeredAt` OR `updated_at < recordsClearedAt`.
  *
+ * # `holder_epoch` (H5 / PR #466) — the THIRD staleness anchor
+ *
+ * A native tokenized `buy_handle` stamps ONLY `holder_epoch` (it must not
+ * move `registered_at`), so without it the seller's records — including the
+ * payment-routing `x1.*` keys — stayed live after a sale. The same functions
+ * take the handle's `holderEpoch` (0 if absent) and judge a text record
+ * stale when `updated_at < max(registeredAt, holderEpoch, recordsClearedAt)`
+ * — the on-chain `name_pays_to` rule and the address-record reader's rule.
+ *
+ * # Keys are compared BYTE-EXACT (BOM-preserving decode)
+ *
+ * The program accepts any UTF-8 key of 1..=64 bytes, including one that
+ * starts with a U+FEFF byte-order mark. A default `TextDecoder` STRIPS a
+ * leading BOM, so a key stored as `EF BB BF "x1.shield"` used to read back
+ * as `"x1.shield"` — a record delegate could spoof a routing key. Keys here
+ * are decoded with `ignoreBOM: true`, so the BOM survives into `key` and the
+ * decoded string is equal to a lookup key only when the raw bytes are. Use
+ * {@link findTextRecord} to look up a specific key.
+ *
  * # These records count (#7384)
  *
  * `create_text_record` increments — and `close_text_record` decrements —
@@ -149,6 +168,21 @@ export async function hashTextKey(key) {
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
     return new Uint8Array(digest);
 }
+/**
+ * Decode a stored KEY: strict UTF-8 with the byte-order mark PRESERVED
+ * (`ignoreBOM: true`). A default decoder silently drops a leading U+FEFF,
+ * which made `EF BB BF "x1.shield"` read back as `"x1.shield"`. With the BOM
+ * kept, `decoded === key` holds exactly when the raw bytes are identical
+ * (UTF-8 is a bijection on valid input). Null when not valid UTF-8.
+ */
+export function textKeyFromBytes(keyBytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(keyBytes);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Render stored value bytes as text: a STRICT UTF-8 decode, or null when the
  * bytes are not valid UTF-8 (binary values like `contenthash`). Callers
@@ -174,15 +208,18 @@ export function textValueToString(value) {
  * `registeredAt` is the owning Handle's `registered_at`, decoded by the
  * caller from the Handle account — it decides `stale`. `recordsClearedAt` is
  * that same Handle's `recordsClearedAt` (0 if never cleared, #8139), a
- * SECOND independent staleness anchor. There is intentionally no overload
- * without either (see the module docs).
+ * SECOND independent staleness anchor. `holderEpoch` is that Handle's
+ * `holderEpoch` (H5, 0 if absent): stale when
+ * `updated_at < max(registeredAt, holderEpoch, recordsClearedAt)`. It
+ * defaults to `0n` only for backward compatibility; every caller that has a
+ * decoded Handle should pass it (a payment-routing reader MUST).
  *
  * Returns null for anything that is not a TextRecord: wrong length, wrong
  * discriminator, lengths that do not fit, or a key that is not valid UTF-8
  * (the program's Borsh `String` guarantees it is, so that is not a
  * TextRecord).
  */
-export function decodeTextRecord(raw, account, registeredAt, recordsClearedAt) {
+export function decodeTextRecord(raw, account, registeredAt, recordsClearedAt, holderEpoch = 0n) {
     if (raw.length !== TEXT_RECORD_LEN)
         return null;
     for (let i = 0; i < 8; i++) {
@@ -207,9 +244,15 @@ export function decodeTextRecord(raw, account, registeredAt, recordsClearedAt) {
     const value = raw.slice(o, o + valueLen);
     o += valueLen;
     const updatedAt = dv.getBigInt64(o, true);
-    const key = textValueToString(keyBytes);
+    // BOM-preserving: see textKeyFromBytes / the module docs.
+    const key = textKeyFromBytes(keyBytes);
     if (key === null)
         return null; // Borsh Strings are always valid UTF-8
+    // Same rule as name_pays_to and decodeRecord: written before the current
+    // ownership epoch (register, native tokenized sale, or clear_records).
+    let epoch = registeredAt > holderEpoch ? registeredAt : holderEpoch;
+    if (recordsClearedAt > epoch)
+        epoch = recordsClearedAt;
     return {
         account,
         handle,
@@ -217,7 +260,7 @@ export function decodeTextRecord(raw, account, registeredAt, recordsClearedAt) {
         value,
         text: textValueToString(value),
         updatedAt,
-        stale: updatedAt < registeredAt || updatedAt < recordsClearedAt,
+        stale: updatedAt < epoch,
     };
 }
 /** The text records the CURRENT owner actually has — `stale` ones excluded.
@@ -225,6 +268,33 @@ export function decodeTextRecord(raw, account, registeredAt, recordsClearedAt) {
 export function liveTextRecords(records) {
     return records.filter((r) => !r.stale);
 }
+/**
+ * The LIVE record whose stored key bytes are EXACTLY `key`'s UTF-8 bytes, or
+ * undefined. Use this (not `records.find((r) => r.key === key)`) for any key
+ * that routes funds or changes behaviour (`x1.shield`, `x1.pool`, ...).
+ *
+ * Byte-exact by construction: keys are decoded BOM-preserving, so a
+ * `U+FEFF`-prefixed look-alike never equals `key`; the raw bytes are compared
+ * again here as defence in depth. If more than one live record matches
+ * (impossible for well-formed PDAs, since the address is derived from
+ * sha256(key)), it returns undefined: ordering never decides which record
+ * routes.
+ */
+export function findTextRecord(records, key) {
+    const want = new TextEncoder().encode(key);
+    let hit;
+    for (const r of records) {
+        if (r.stale)
+            continue;
+        const got = new TextEncoder().encode(r.key);
+        if (got.length !== want.length || got.some((b, i) => b !== want[i]))
+            continue;
+        if (hit !== undefined)
+            return undefined; // ambiguous: refuse, never pick
+        hit = r;
+    }
+    return hit;
+}
 /**
  * Fetch every TextRecord account of a handle — one `getProgramAccounts`
  * call, filtered by the RPC on size (377), the TextRecord discriminator at
@@ -236,12 +306,14 @@ export function liveTextRecords(records) {
  * `registeredAt` is `Handle.registered_at` as decoded from the Handle
  * account the caller already has — the staleness rule needs it, and there
  * is no variant of this function without it. `recordsClearedAt` is that same
- * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through.
+ * Handle's `recordsClearedAt` (0 if never cleared, #8139) — pass it through,
+ * and `holderEpoch` (H5; defaults to 0n for backward compatibility, but pass
+ * it: a native tokenized sale moves only this anchor).
  * Every record is returned, stale ones flagged, so an owner surface can show
  * what a previous owner left behind; anything that renders a profile takes
  * {@link liveTextRecords}.
  */
-export async function fetchTextRecords(rpc, programId, handleAccount, registeredAt, recordsClearedAt) {
+export async function fetchTextRecords(rpc, programId, handleAccount, registeredAt, recordsClearedAt, holderEpoch = 0n) {
     const res = (await rpc("getProgramAccounts", [
         programId,
         {
@@ -260,7 +332,7 @@ export async function fetchTextRecords(rpc, programId, handleAccount, registered
         const raw = new Uint8Array(bin.length);
         for (let i = 0; i < bin.length; i++)
             raw[i] = bin.charCodeAt(i);
-        const decoded = decodeTextRecord(raw, a.pubkey, registeredAt, recordsClearedAt);
+        const decoded = decodeTextRecord(raw, a.pubkey, registeredAt, recordsClearedAt, holderEpoch);
         // Defence in depth: the memcmp filter should guarantee the handle
         // match, but a wrong offset would silently attribute someone else's
         // record to this handle. A malformed account is skipped, not fatal.

package/dist/types.d.ts

@@ -98,6 +98,9 @@ export type ResolveErrorCode = "unrecognized" | "ambiguous" | "invalid-handle" |
  *  isn't "any-verified"/{kind}/{anyOf}) — a programming error, surfaced as a
  *  typed ResolveError rather than a raw TypeError. */
  | "invalid-input"
+/** The name is held by the X1ID treasury (a reserved name): it is not a
+ *  person and must never be offered as a payment target. */
+ | "reserved"
 /**
  * A reachable namespace exists for this name, but the adapter that would
  * resolve it is not configured on this deployment (e.g. no `ETH_RPC_URL` for

package/dist/x402Receipt.d.ts

@@ -0,0 +1,246 @@
+/**
+ * x402 payment receipts on chain (#8324, wired by [Pay 10] / WP 8833):
+ * `record_x402_receipt`, its `X402ReceiptRecorded` event and the per-handle
+ * `AgentPaymentStats` tally.
+ *
+ * Hand-rolled like the rest of this package — no Anchor client, no
+ * `@solana/web3.js`. The builder returns the transport-neutral
+ * {@link BuiltInstruction} (`delegate.ts` has the two-line web3.js adapter).
+ *
+ * # What a receipt proves (and what it does not)
+ *
+ * The instruction is ATTESTOR-SIGNED (`has_one = attestor` on
+ * `["attestor_config"]`). The program does NOT look at the payment itself: it
+ * does not introspect the Instructions sysvar, does not read `settled_sig`'s
+ * transaction, and does not check `amount` / `mint` against anything. A
+ * receipt therefore proves exactly one thing — "the configured attestor key
+ * stamped this payment" — and the attestor is trusted to have confirmed the
+ * settlement off chain first (`docs/x402-receipts.md`, option B). The
+ * `settled_sig` it carries is the audit anchor: anyone can fetch that
+ * transaction and check it. Never present a receipt as more than that.
+ *
+ * Both handles must be live `Handle` accounts and must differ
+ * (`X402SelfReceipt`, 6085). A scoped handle (`["handle", [len], label,
+ * name]`) needs its `["namespace", label]` account in `namespaces` (the
+ * program scans remaining accounts for it); a bare handle needs nothing.
+ *
+ * Cost: the attestor is the fee payer and pays the rent of each
+ * `AgentPaymentStats` account the first time a handle is touched (81 bytes
+ * each). On X1 the fee is 10 lamports per REQUESTED compute unit plus 1,500
+ * per signature, so always set a compute-unit limit: simulate and use
+ * {@link x402ReceiptCuLimitFromSimulation}, or fall back to
+ * {@link RECORD_X402_RECEIPT_CU_LIMIT}.
+ */
+import type { AddressLike, BuiltInstruction } from "./delegate.js";
+import type { PdaFinder } from "./namespacePricing.js";
+/** Anchor instruction discriminator: `sha256("global:record_x402_receipt")[0..8]`. */
+export declare const RECORD_X402_RECEIPT_DISCRIMINATOR: Uint8Array;
+/** Anchor event discriminator: `sha256("event:X402ReceiptRecorded")[0..8]`.
+ *  An emitted event is logged as `Program data: <base64(disc ‖ borsh)>`. */
+export declare const X402_RECEIPT_RECORDED_EVENT_DISCRIMINATOR: Uint8Array;
+/** Anchor account discriminator: `sha256("account:AgentPaymentStats")[0..8]`. */
+export declare const AGENT_PAYMENT_STATS_DISCRIMINATOR: Uint8Array;
+/** Seed prefix of the stats PDA: `["x402_stats", handleAccount]`. */
+export declare const AGENT_PAYMENT_STATS_SEED = "x402_stats";
+/** `AgentPaymentStats` size: disc(8) + handle(32) + 4×u64(32) + last_at(8) + bump(1). */
+export declare const AGENT_PAYMENT_STATS_LEN = 81;
+/** `X402ReceiptRecorded` encoded size: disc(8) + payer(32) + payee(32) +
+ *  amount(8) + mint(32) + resource_hash(32) + settled_sig(64) + timestamp(8). */
+export declare const X402_RECEIPT_EVENT_LEN = 216;
+/** `record_x402_receipt` instruction data size: disc + amount + mint +
+ *  resource_hash + settled_sig. */
+export declare const RECORD_X402_RECEIPT_DATA_LEN: number;
+/** `X402SelfReceipt`: payer and payee handle are the same account. */
+export declare const X402_SELF_RECEIPT_ERROR = 6085;
+/**
+ * Static compute-unit CEILING for a transaction carrying ONE
+ * `record_x402_receipt` (plus its compute-budget instruction), for callers
+ * that cannot simulate first. Measured in litesvm against the built program
+ * (programs/x1-handles/tests/x402_receipt_sdk_e2e.rs): ~40.0k CU when both
+ * stats accounts are created (first touch), ~28.7k CU after, with stats-PDA
+ * bumps 255/254. The cost is not constant: Anchor re-derives each stats PDA
+ * with `find_program_address` on every call, so a handle whose stats bump is
+ * lower costs ~1.5k CU more per step below 255. X1 charges the REQUESTED
+ * limit (10 lamports per CU), so the better practice — what dev-api does — is
+ * to simulate and request {@link x402ReceiptCuLimitFromSimulation} of the
+ * measured units, using this only as the fallback / upper bound.
+ */
+export declare const RECORD_X402_RECEIPT_CU_LIMIT = 60000;
+/** A tight limit from a simulation's `unitsConsumed`: +10% (at least 2,000
+ *  CU), rounded up to a thousand, never above `ceiling`. */
+export declare function x402ReceiptCuLimitFromSimulation(unitsConsumed: number, ceiling?: number): number;
+/** A transaction signature as its 64 raw bytes (from base58 or bytes). */
+export declare function x402SettledSigBytes(sig: string | Uint8Array): Uint8Array;
+/**
+ * The `resource_hash` x1id stamps: sha256 of the x402 `resource` URL the
+ * payment bought, e.g. `https://api.x1id.io/v1/resolve`. The ENDPOINT, not the
+ * exact request — a receipt is public forever, and hashing the full request
+ * (`/v1/resolve/alice`) would let anyone brute-force what an agent looked up.
+ */
+export declare function x402ResourceHash(resource: string): Uint8Array;
+/** `["x402_stats", handleAccount]` — the second seed is the 32 raw bytes of
+ *  the Handle ACCOUNT address. */
+export declare function findAgentPaymentStatsPda(find: PdaFinder, programId: AddressLike, handle: AddressLike): Promise<string>;
+export interface RecordX402ReceiptArgs {
+    /** Amount paid, in the asset's base units (u64). */
+    readonly amount: bigint;
+    /** The asset's mint (wrapped-native for XNT on the x402 X1 rail). */
+    readonly mint: AddressLike;
+    /** 32 bytes — see {@link x402ResourceHash}. */
+    readonly resourceHash: Uint8Array;
+    /** The settled payment's transaction signature (base58 or 64 bytes). */
+    readonly settledSig: string | Uint8Array;
+}
+/** Borsh args after the discriminator: amount u64, mint, resource_hash[32], settled_sig[64]. */
+export declare function encodeRecordX402ReceiptArgs(a: RecordX402ReceiptArgs): Uint8Array;
+export interface RecordX402ReceiptParams extends RecordX402ReceiptArgs {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The configured attestor (`AttestorConfig.attestor`). Signer, writable:
+     *  pays the stats accounts' first-touch rent. Use it as fee payer too. */
+    readonly attestor: AddressLike;
+    /** The `["attestor_config"]` PDA. */
+    readonly attestorConfig: AddressLike;
+    /** The paying agent's live Handle account. */
+    readonly payerHandle: AddressLike;
+    /** The paid agent's live Handle account. Must differ from payerHandle. */
+    readonly payeeHandle: AddressLike;
+    /** `["x402_stats", payerHandle]` ({@link findAgentPaymentStatsPda}). */
+    readonly payerStats: AddressLike;
+    /** `["x402_stats", payeeHandle]`. */
+    readonly payeeStats: AddressLike;
+    /** `["namespace", label]` accounts of any SCOPED handle among the two
+     *  (remaining accounts, read-only). Omit for bare handles. */
+    readonly namespaces?: readonly AddressLike[];
+}
+/**
+ * Build `record_x402_receipt`. Accounts in `RecordX402Receipt` order:
+ * attestor(s,w) attestor_config payer_handle payee_handle payer_stats(w)
+ * payee_stats(w) system_program, then any namespace accounts.
+ */
+export declare function buildRecordX402ReceiptIx(p: RecordX402ReceiptParams): BuiltInstruction;
+/** A decoded `X402ReceiptRecorded` event. */
+export interface X402ReceiptRecorded {
+    readonly payerHandle: string;
+    readonly payeeHandle: string;
+    readonly amount: bigint;
+    readonly mint: string;
+    readonly resourceHash: Uint8Array;
+    /** base58 transaction signature of the settled payment. */
+    readonly settledSig: string;
+    /** Unix seconds (cluster clock at recording). */
+    readonly timestamp: bigint;
+}
+/** Decode one event payload (the bytes of a `Program data:` line). null when
+ *  it is not an `X402ReceiptRecorded`. */
+export declare function decodeX402ReceiptRecorded(raw: Uint8Array): X402ReceiptRecorded | null;
+/** Encode an event the way the program emits it (tests / fixtures). */
+export declare function encodeX402ReceiptRecorded(e: {
+    payerHandle: AddressLike;
+    payeeHandle: AddressLike;
+    amount: bigint;
+    mint: AddressLike;
+    resourceHash: Uint8Array;
+    settledSig: string | Uint8Array;
+    timestamp: bigint;
+}): Uint8Array;
+/**
+ * Every `X402ReceiptRecorded` among a transaction's log lines, attributed to
+ * `programId`'s OWN invoke frames only (a look-alike `Program data:` line
+ * printed by another program is ignored).
+ */
+export declare function parseX402ReceiptEvents(logs: readonly string[], programId: AddressLike): X402ReceiptRecorded[];
+/** A decoded `AgentPaymentStats` account. `totalPaid` / `totalReceived` are
+ *  raw sums across whatever mint each receipt used — never one asset figure;
+ *  the counts are the unambiguous signal. */
+export interface AgentPaymentStats {
+    readonly handle: string;
+    readonly paymentsMadeCount: bigint;
+    readonly totalPaid: bigint;
+    readonly paymentsReceivedCount: bigint;
+    readonly totalReceived: bigint;
+    readonly lastAt: bigint;
+    readonly bump: number;
+}
+/** Decode an `AgentPaymentStats` account (discriminator + exact length
+ *  checked); null for anything else. */
+export declare function decodeAgentPaymentStats(raw: Uint8Array): AgentPaymentStats | null;
+/** Encode an `AgentPaymentStats` account (tests / fixtures). */
+export declare function encodeAgentPaymentStats(s: Omit<AgentPaymentStats, "handle"> & {
+    handle: AddressLike;
+}): Uint8Array;
+/** Fee (lamports) of one receipt transaction on X1: 10 lamports per
+ *  requested CU + 1,500 per signature (rent of new stats accounts excluded). */
+export declare function x402ReceiptTxFeeLamports(cuLimit?: number, signatures?: number): number;
+/** Seed of the receipt-signer singleton: `["receipt_signer_config"]`. */
+export declare const RECEIPT_SIGNER_CONFIG_SEED = "receipt_signer_config";
+/** Seed of a handle's O(1) payment tally (alias of {@link AGENT_PAYMENT_STATS_SEED}). */
+export declare const X402_STATS_SEED = "x402_stats";
+/** `sha256("global:record_x402_receipt_v2")[..8]`. */
+export declare const RECORD_X402_RECEIPT_V2_DISCRIMINATOR: Uint8Array;
+/** `sha256("global:set_receipt_signer")[..8]`. */
+export declare const SET_RECEIPT_SIGNER_DISCRIMINATOR: Uint8Array;
+/** `sha256("account:ReceiptSignerConfig")[..8]`. */
+export declare const RECEIPT_SIGNER_CONFIG_DISCRIMINATOR: Uint8Array;
+/** `RegistryError::NotReceiptSigner`: v2 signed by neither role. */
+export declare const X402_NOT_RECEIPT_SIGNER_ERROR = 6157;
+/** `RegistryError::X402ReceiptPayerIsSigner`: v2 with `payer == signer`
+ *  (Sentinel run-011: the X1ID receipt key never pays). */
+export declare const X402_RECEIPT_PAYER_IS_SIGNER_ERROR = 6232;
+/** `["receipt_signer_config"]`. */
+export declare function findReceiptSignerConfigPda(find: PdaFinder, programId: AddressLike): Promise<string>;
+/** `["x402_stats", handle]` (alias of {@link findAgentPaymentStatsPda}). */
+export declare function findX402StatsPda(find: PdaFinder, programId: AddressLike, handle: AddressLike): Promise<string>;
+/** Decode a `ReceiptSignerConfig` (`signer` base58; the default key
+ *  `11111111111111111111111111111111` means the role is disabled). */
+export declare function decodeReceiptSignerConfig(data: Uint8Array): {
+    readonly signer: string;
+    readonly bump: number;
+} | null;
+export interface RecordX402ReceiptV2Params extends RecordX402ReceiptArgs {
+    readonly programId: AddressLike;
+    /** Signer: the receipt signer or the attestor. It only CO-SIGNS (owner
+     *  rule: X1ID pays for nothing on chain). */
+    readonly signer: AddressLike;
+    /** REQUIRED signer (writable) that funds first-touch stats rent and
+     *  should be the tx fee payer: the submitter (e.g. the API buyer or the
+     *  merchant), never the receipt key. Must differ from `signer`; the
+     *  program refuses `payer == signer` (6232). */
+    readonly payer: AddressLike;
+    /** `["attestor_config"]`. */
+    readonly attestorConfig: AddressLike;
+    /** `["receipt_signer_config"]` ({@link findReceiptSignerConfigPda}). */
+    readonly receiptSignerConfig: AddressLike;
+    readonly payerHandle: AddressLike;
+    /** Must differ from payerHandle. */
+    readonly payeeHandle: AddressLike;
+    /** {@link findAgentPaymentStatsPda}(payerHandle). */
+    readonly payerStats: AddressLike;
+    /** {@link findAgentPaymentStatsPda}(payeeHandle). */
+    readonly payeeStats: AddressLike;
+    /** Scoped-name handles only: their `["namespace", label]` accounts. */
+    readonly namespaces?: readonly AddressLike[];
+}
+/**
+ * Build `record_x402_receipt_v2`: the same args as v1. Accounts
+ * (`RecordX402ReceiptV2`): signer(s), payer(s,w), attestor_config,
+ * receipt_signer_config, payer_handle, payee_handle, payer_stats(w),
+ * payee_stats(w), system_program, then any namespaces. Make `payer` the
+ * transaction fee payer so the receipt signer's key holds no XNT. Throws when
+ * `payer` is missing or equals `signer`.
+ */
+export declare function buildRecordX402ReceiptV2Ix(p: RecordX402ReceiptV2Params): BuiltInstruction;
+export interface SetReceiptSignerParams {
+    readonly programId: AddressLike;
+    /** Signer: `Config.admin` (pays the one-time init). */
+    readonly admin: AddressLike;
+    /** `["config"]`. */
+    readonly config: AddressLike;
+    /** {@link findReceiptSignerConfigPda}. */
+    readonly receiptSignerConfig: AddressLike;
+    /** The new receipt signer; the default key (all zeros) disables the role. */
+    readonly signer: AddressLike;
+}
+/** `set_receipt_signer(signer)`. Accounts (`SetReceiptSigner`): admin(s,w),
+ *  config, receipt_signer_config(w), system_program. */
+export declare function buildSetReceiptSignerIx(p: SetReceiptSignerParams): BuiltInstruction;