@elisym/commerce 0.2.0 → 0.3.0

package/dist/buyer.d.ts

@@ -0,0 +1,921 @@
+import { NostrEvent, EventTemplate, VerifiedEvent, Filter } from 'nostr-tools';
+import { SimplePool } from 'nostr-tools/pool';
+import { Rpc, SolanaRpcApi, KeyPairSigner } from '@solana/kit';
+import { ChainFamily, Network, ChainConfig, Asset, PaymentRequestData } from '@elisym/pay-core';
+import { t as OfferWarning, F as FetchLike, b as DomainKeys, X as VerifiedOffer, H as PayoutTarget, r as OfferRefusal, x as OrderStatusMessage } from './verify-offer-BZ_a9x3L.js';
+import 'zod';
+
+/**
+ * Relays the widget always queries for the offer and the store's inbox list,
+ * outside the cap on store-named relays: the store's own relays hold neither the
+ * owner's payout list nor its authorization, and the store key must not choose
+ * where those reads go.
+ */
+declare const DEFAULT_RELAYS: readonly string[];
+/** At most this many relays named by the store (its inbox list, naddr hints). */
+declare const STORE_RELAY_CAP = 8;
+/** A relay URL longer than this is not one. */
+declare const MAX_RELAY_URL_LENGTH = 256;
+/** An offer snapshot older than this is verified again before ordering or paying. */
+declare const OFFER_SNAPSHOT_MAX_AGE_SECS = 120;
+/** Store inbox relays that must acknowledge the order before the wallet opens. */
+declare const ORDER_ACK_TARGET = 2;
+/** How long one relay query waits before it answers with what it has. */
+declare const RELAY_QUERY_MAX_WAIT_MS = 4000;
+/** The most one relay's query may take in all, AUTH and a re-subscription included. */
+declare const RELAY_QUERY_DEADLINE_MS = 15000;
+/** How long a publish waits to connect to one relay. */
+declare const RELAY_CONNECT_MAX_WAIT_MS = 6000;
+/**
+ * The most one relay's publish may take in all: connect, OK, AUTH and a retry.
+ * The OK itself is bounded by the relay library's own publish timeout.
+ */
+declare const RELAY_PUBLISH_DEADLINE_MS = 20000;
+/** Pauses before a closed long-lived subscription is opened again, growing to the last. */
+declare const SUBSCRIBE_RETRY_MAX_MS = 60000;
+declare const SUBSCRIBE_RETRY_MS: readonly number[];
+/**
+ * How long a subscription must stay open past its EOSE before a close starts the
+ * pauses over: a relay that drops right after EOSE is not retried every second.
+ */
+declare const SUBSCRIBE_STABLE_MS = 30000;
+/** Tries of an order-record write that lost a race with another tab. */
+declare const STORE_WRITE_ATTEMPTS = 5;
+/** The device clock may differ from chain time by at most this much to order. */
+declare const MAX_CLOCK_SKEW_SECS: number;
+/** NIP-59 back-dates a gift wrap up to two days: a read for replies reaches back that far. */
+declare const WRAP_BACKDATE_SECS: number;
+/** The merchant keeps catching up on an order's payments this long after it (plan: 3 days). */
+declare const MERCHANT_CATCH_UP_SECS: number;
+/** No wallet request, first or retry, this close to the end of the merchant's catch-up. */
+declare const PAY_CUTOFF_SECS: number;
+/**
+ * A payment is looked for back to the order's `created_at` minus this margin
+ * (the merchant's own scan margin): the order is dated by the chain, a block a
+ * little behind it may hold the payment.
+ */
+declare const PAYMENT_SCAN_MARGIN_SECS: number;
+/** Compute units the payment transaction asks for: what pay-core's own builder uses. */
+declare const SOLANA_COMPUTE_UNIT_LIMIT = 200000;
+
+/** Whether a value from a relay has the NIP-01 field types. */
+declare function isEventShaped(event: unknown): event is NostrEvent;
+/**
+ * Whether an event's id is its hash and its signature is genuine, checked every
+ * time on a fresh object: `verifyEvent` caches its verdict on the object it is
+ * given, and a spread copy of a genuine event would carry that cache.
+ */
+declare function isGenuineEvent(event: unknown): event is NostrEvent;
+/**
+ * The newest genuine event of `kind` by `author` among everything the relays
+ * returned, or `undefined`. An event dated further ahead than the skew
+ * allowance is ignored, so a far-future copy cannot pin an old value; a tie on
+ * `created_at` goes to the lowest id (NIP-01).
+ */
+declare function newestGenuine(events: readonly unknown[], kind: number, author: string, now: number): NostrEvent | undefined;
+declare function nowSecs(): number;
+
+/** Signs a NIP-42 AUTH event with the buyer key when a relay asks for one. */
+type AuthSigner = (template: EventTemplate) => Promise<VerifiedEvent>;
+interface PublishResult {
+    /** Relays that answered OK. */
+    accepted: string[];
+    /** Relays that refused, failed or timed out, with their reason. */
+    failed: {
+        relay: string;
+        reason: string;
+    }[];
+}
+interface RelayClient {
+    /**
+     * Every event the relays hold for the filters, each once. Nothing is trusted:
+     * the caller checks signatures and authors itself. A relay that fails adds
+     * nothing; it does not fail the query.
+     */
+    query(relays: readonly string[], filters: readonly Filter[]): Promise<NostrEvent[]>;
+    publish(relays: readonly string[], event: NostrEvent): Promise<PublishResult>;
+    /**
+     * Keep listening on each relay for `filter`, each event handed on once. A
+     * relay that closes the subscription is opened again after a pause; one that
+     * asks for AUTH gets it once, signed by the client's key.
+     */
+    subscribe(relays: readonly string[], filter: Filter, onEvent: (event: NostrEvent) => void): {
+        close(): void;
+    };
+    close(): void;
+}
+/** The part of a connected relay the client uses. */
+interface RelayLike {
+    /** Resolves only on the relay's OK true; rejects on a refusal or a timeout. */
+    publish(event: NostrEvent): Promise<string>;
+    auth(signer: AuthSigner): Promise<string>;
+    /** A relay-level subscription: nostr-tools takes a LIST of filters here. */
+    subscribe(filters: Filter[], params: {
+        onevent?: (event: NostrEvent) => void;
+        oneose?: () => void;
+        onclose?: (reason: string) => void;
+    }): {
+        close(reason?: string): void;
+    };
+}
+/** The part of `SimplePool` the client uses, so tests can stand in for relays. */
+interface PoolLike {
+    subscribeEose(relays: string[], filter: Filter, params: {
+        maxWait?: number;
+        onauth?: AuthSigner;
+        onevent?: (event: NostrEvent) => void;
+        onclose?: (reasons: string[]) => void;
+    }): {
+        close(reason?: string): void;
+    };
+    ensureRelay(url: string, params?: {
+        connectionTimeout?: number;
+    }): Promise<RelayLike>;
+    destroy(): void;
+}
+interface RelayClientOptions {
+    /** Answers NIP-42 AUTH challenges (the buyer key). Without it a relay that asks is refused. */
+    auth?: AuthSigner;
+    pool?: PoolLike;
+}
+/**
+ * A pool that never answers an AUTH challenge on its own: the buyer key signs
+ * only for a relay that refuses a request with auth-required (the query's
+ * `onauth`, the publish retry), not for every relay that merely asks on connect.
+ * Exported for tests.
+ */
+declare function createPool(): SimplePool;
+declare function createRelayClient(options?: RelayClientOptions): RelayClient;
+
+/**
+ * A store-named relay URL the widget may connect to, in one spelling, or
+ * `undefined`. Only `wss:` on a public DNS name: the URL comes from the store
+ * (its inbox list) or the page (naddr hints), so a loopback, private or IP
+ * literal host - or plain `ws:` - is never contacted.
+ */
+declare function normalizeRelayUrl(value: unknown): string | undefined;
+/**
+ * The server a relay URL reaches (host and port): `wss://r.example.com` and
+ * `wss://r.example.com/inbox` are usually one relay, and count once.
+ */
+declare function relayHost(url: string): string;
+/** Each usable URL once, in the order given. */
+declare function uniqueRelays(values: readonly unknown[]): string[];
+interface StoreRelaySources {
+    /** The relays of the store's current inbox list (kind 10050): where it reads and replies. */
+    inbox?: readonly unknown[];
+    /** Older inbox relays that acknowledged this order: kept for republishing only. */
+    acknowledged?: readonly unknown[];
+    /** Relay hints from the product naddr. */
+    hints?: readonly unknown[];
+}
+/**
+ * The store-named relays, capped at `STORE_RELAY_CAP` in a fixed priority: the
+ * current inbox first (the widget listens there), then old relays that
+ * acknowledged the order, then naddr hints - so a page's hints can never crowd
+ * out the store's inbox.
+ */
+declare function storeRelays(sources: StoreRelaySources): string[];
+/**
+ * Where the offer and the store's inbox list are read: the default relays,
+ * always and outside the cap, plus the capped store-named ones.
+ */
+declare function readRelays(sources: StoreRelaySources): string[];
+
+interface StoreInbox {
+    /** The store's inbox relays the widget may use, capped, in the store's order. */
+    relays: string[];
+    /** The kind 10050 they came from. */
+    event: NostrEvent;
+}
+/**
+ * The store's inbox relays from the newest genuine kind 10050 signed by the store
+ * key among everything the relays returned - the same rule as for the payout list,
+ * since a stale copy from one relay would send the order where the merchant no
+ * longer reads. `undefined` when there is none, or it names no usable relay: the
+ * widget then refuses before ordering.
+ */
+declare function newestStoreInbox(events: readonly unknown[], storePubkey: string, now?: number): StoreInbox | undefined;
+/**
+ * Read the store's inbox list from the default relays - always, outside the cap -
+ * plus the capped store-named relays, and pick it by `newestStoreInbox`.
+ */
+declare function readStoreInbox(client: RelayClient, sources: StoreRelaySources, storePubkey: string, now?: number): Promise<StoreInbox | undefined>;
+
+/** Warnings the buyer must confirm, for the exact payout, before paying. */
+declare const CONFIRM_WARNINGS: readonly OfferWarning[];
+/** A payout the widget can pay: priced in that coin's subunits. */
+interface PricedPayout {
+    target: PayoutTarget;
+    /** The product's price in the coin's subunits (quantity 1). */
+    amount: bigint;
+}
+type WidgetRefusal = OfferRefusal
+/** The page's origin is opaque or not an http(s) origin. */
+ | 'bad_page_origin'
+/** No payout the widget can price and pay on the allowed rails and networks. */
+ | 'no_payable_payout';
+type LoadedOffer = {
+    ok: true;
+    offer: VerifiedOffer;
+    /** `30402:<store>:<d>`: the key the widget's records are indexed by. */
+    productAddress: string;
+    payouts: PricedPayout[];
+    /** Warnings that need an explicit confirmation before paying. */
+    confirm: OfferWarning[];
+    /** Warnings that are only shown. */
+    notices: OfferWarning[];
+    /** The naddr's usable relay hints (store-named, so capped with the inbox later). */
+    hints: string[];
+    /** Where the offer was read: the default relays plus the capped hints. */
+    relays: string[];
+    /** When this snapshot was taken (seconds). */
+    snapshotAt: number;
+} | {
+    ok: false;
+    refusal: WidgetRefusal;
+    message: string;
+};
+interface StorePins {
+    /** The owner pinned at the first purchase from this store. */
+    pinnedOwnerPubkey?: string;
+    /** Every payout of every verified offer that delivered from this store. */
+    knownPayouts?: readonly {
+        caip19: string;
+        address: string;
+    }[];
+}
+interface LoadOfferOptions {
+    client: RelayClient;
+    /** The embedding page's origin, from the accepted `hello`. */
+    pageOrigin: string;
+    /** Set by the page's `strict-origin` attribute: also refuse at levels B and C. */
+    strictOrigin?: boolean;
+    pins?: StorePins;
+    /** Rails the widget can pay on now: required, so a new rail is offered only once it is built. */
+    families: readonly ChainFamily[];
+    /** The page's `network` attribute: only payouts on this network are offered. */
+    network?: Network;
+    now?: number;
+    /** Domain lookups (nostr.json, DoH); defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    resolveDomain?: (nip05: string) => Promise<DomainKeys | undefined>;
+}
+/** Whether `value` is a real http(s) origin, in its canonical spelling. */
+declare function isPageOrigin(value: unknown): value is string;
+/** Whether a snapshot taken at `snapshotAt` must be verified again before use. */
+declare function isSnapshotStale(snapshotAt: number, now?: number): boolean;
+/**
+ * Verify the offer behind `naddr` for this page and apply the widget's own
+ * policy on top: a level A store the page is not on is refused (not only warned
+ * about), and only payouts the widget can price and pay are offered.
+ */
+declare function loadOffer(naddr: string, options: LoadOfferOptions): Promise<LoadedOffer>;
+/**
+ * The offer for a buyer that is not a web page (an AI agent through the MCP):
+ * the same verification, with no page origin, so no origin rule applies. The
+ * caller shows the trust level and the verified domain to its user instead.
+ */
+declare function loadOfferForAgent(naddr: string, options: Omit<LoadOfferOptions, 'pageOrigin' | 'strictOrigin'>): Promise<LoadedOffer>;
+
+/**
+ * Where one order stands. The order is sent and acknowledged BEFORE any wallet
+ * opens (`created` -> `ordered`); a payment attempt holds a marker (`paying`);
+ * a payment found on chain waits for the store (`paid`).
+ */
+type OrderState = 
+/** Written, the order not yet acknowledged by the store's inbox relays. */
+'created'
+/** Acknowledged; no payment attempt holds a marker. */
+ | 'ordered'
+/** A payment attempt holds the marker. */
+ | 'paying'
+/** The payment was found on chain; waiting for the store's status. */
+ | 'paid'
+/** The store delivered. */
+ | 'completed'
+/** The store cancelled with a refund. */
+ | 'refunded'
+/** No payment by the deadline: a new order may start (it is still reconciled). */
+ | 'ended-unpaid'
+/** Tempo: the money sits with the recipient's transfer policy guard. */
+ | 'blocked';
+type PaymentMarker = {
+    rail: 'solana';
+    /** Random per attempt: every clear or replace is a compare-and-swap on it. */
+    attemptId: string;
+    setAt: number;
+    /** The blockhash the widget set; the widget broadcasts only a message with this lifetime. */
+    blockhash: string;
+    /** Decimal string: the attempt is over once `finalized` passes this height. */
+    lastValidBlockHeight: string;
+    /**
+     * Decimal string: the slot the blockhash was read at. Nothing of this attempt can
+     * sit below it, so an RPC whose ledger starts above it cannot prove "not paid".
+     */
+    slot?: string;
+    /** The signature of the transaction the wallet signed, once known. */
+    signature?: string;
+    /**
+     * The signed wire transaction (base64), written with its signature BEFORE the
+     * first broadcast and rebroadcast until it lands or its blockhash expires.
+     */
+    signedTransaction?: string;
+} | {
+    rail: 'tempo';
+    attemptId: string;
+    setAt: number;
+    /** Decimal string: the finalized block read before the wallet call. */
+    floorBlock: string;
+    /** The hash the wallet returned. */
+    txHash?: string;
+    /** A bundle id (`wallet_sendCalls`): approved, the hash comes later. */
+    bundleId?: string;
+};
+interface OrderStatus {
+    status: 'pending' | 'confirmed' | 'completed' | 'cancelled';
+    /** When the widget accepted it (seconds). */
+    at: number;
+    delivery?: string;
+    refunded?: boolean;
+}
+interface OrderRecord {
+    orderId: string;
+    /** `30402:<store>:<d>`: records are indexed by it, never by the naddr string. */
+    productAddress: string;
+    storePubkey: string;
+    /** The one-time buyer key for this order (hex). */
+    buyerSecretKey: string;
+    buyerPubkey: string;
+    /** The order rumor's `created_at` (chain time, seconds). */
+    createdAt: number;
+    /** Bumped on every write: a writer states the version it judged. */
+    version: number;
+    state: OrderState;
+    payout: {
+        caip19: string;
+        address: string;
+    };
+    /** Decimal string of subunits. */
+    amount: string;
+    /** The receipt's `medium`: `solana`, `solana-devnet`, `tempo`, `tempo-moderato`. */
+    medium: string;
+    /** The derived payment reference (base58) or memo (0x hex). */
+    reference: string;
+    /** The verified offer the order was placed against. */
+    offer: VerifiedOffer;
+    /** The composed payment request, written once before the first marker. */
+    paymentRequest?: string;
+    /** Signed wraps, republished byte for byte on resume. */
+    orderWrap?: NostrEvent;
+    receiptWrap?: NostrEvent;
+    /** The store inbox relays the order went to. */
+    inboxRelays: string[];
+    /** Relays that answered OK to the order wrap. */
+    acknowledgedRelays: string[];
+    marker?: PaymentMarker;
+    /** The transaction that paid, once found. */
+    paidTx?: string;
+    status?: OrderStatus;
+}
+declare const TERMINAL_STATES: readonly OrderState[];
+declare function isTerminal(record: Pick<OrderRecord, 'state'>): boolean;
+/**
+ * Whether the record keeps any other order for the same product from paying: a
+ * set marker until the attempt provably ended (`ended-unpaid`, or `blocked` on
+ * Tempo), and a found payment until the store answers. "No stored signature" is
+ * never "never sent" on its own.
+ */
+declare function holdsPayExclusion(record: Pick<OrderRecord, 'state' | 'marker' | 'paidTx'>): boolean;
+/**
+ * The record the widget shows for a product: the best rank (`showRank`), then
+ * the newest within it.
+ */
+declare function recordToShow(records: readonly OrderRecord[]): OrderRecord | undefined;
+
+/** Per store, what earlier purchases pinned (TOFU). */
+interface StorePinsRecord {
+    storePubkey: string;
+    pinnedOwnerPubkey: string;
+    /** The union of every payout of every verified offer that delivered from this store. */
+    knownPayouts: {
+        caip19: string;
+        address: string;
+    }[];
+}
+type StoreWrite = {
+    ok: true;
+    record: OrderRecord;
+} | {
+    ok: false;
+    /**
+     * `missing`: no such record. `conflict`: the record (its version or its
+     * marker's attempt) is not the one the caller judged. `exclusion`: another
+     * record for this product holds a live payment. `not_ready`: the record's
+     * state does not allow this write.
+     */
+    reason: 'missing' | 'conflict' | 'exclusion' | 'not_ready';
+    /** For `exclusion`: the order holding it. */
+    holder?: string;
+};
+/**
+ * Fields a plain update may change. What the order and its payment were made of
+ * (payout, amount, reference, offer, ...) is fixed when the record is added; the
+ * marker and the version have their own paths.
+ */
+type RecordPatch = Partial<Pick<OrderRecord, 'state' | 'paymentRequest' | 'orderWrap' | 'receiptWrap' | 'inboxRelays' | 'acknowledgedRelays' | 'paidTx' | 'status'>>;
+/**
+ * Where order records live. Every money rule is judged by the core (below) on
+ * what `transactProduct` hands it; a backend only makes that read-judge-write
+ * atomic and durable: the checkout's IndexedDB (one readwrite transaction with
+ * strict durability), the MCP's locked, fsynced file, or memory in tests.
+ *
+ * `fn` is synchronous: the rule runs between the read and the write of ONE
+ * transaction (an `await` inside would let IndexedDB commit part-way). A
+ * backend resolves only once the writes are committed; a write that did not
+ * commit did not happen, and nothing is decided on it.
+ */
+interface OrderBackend {
+    read(orderId: string): Promise<OrderRecord | undefined>;
+    /** Every record for a product (any order; the store sorts). */
+    forProduct(productAddress: string): Promise<OrderRecord[]>;
+    /** Read the product's records, run `fn`, commit its writes (whole records, by `orderId`). */
+    transactProduct<T>(productAddress: string, fn: (records: readonly OrderRecord[]) => {
+        write?: readonly OrderRecord[];
+        result: T;
+    }): Promise<T>;
+    readPins(storePubkey: string): Promise<StorePinsRecord | undefined>;
+    /** Read one store's pins, run `fn`, commit its write. */
+    transactPins<T>(storePubkey: string, fn: (pins: StorePinsRecord | undefined) => {
+        write?: StorePinsRecord;
+        result: T;
+    }): Promise<T>;
+}
+/** A rule's verdict: what the caller is told, and the record to write when it is `ok`. */
+interface Judged {
+    result: StoreWrite;
+    write?: readonly OrderRecord[];
+}
+/** A new order: `created`, version 1, no marker, an id not yet used. */
+declare function judgeAdd(records: readonly OrderRecord[], record: OrderRecord): Judged;
+/** Plain fields of the record the caller judged at `expectedVersion`. */
+declare function judgeUpdate(records: readonly OrderRecord[], orderId: string, expectedVersion: number, patch: RecordPatch): Judged;
+/**
+ * Test-and-set the payment marker immediately before the wallet call. Refused
+ * unless the record is still the one judged, acknowledged (`ordered`), holds
+ * its composed request and no marker - and no OTHER record for the product
+ * holds a live payment (two tabs cannot both pay).
+ */
+declare function judgeSetMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, marker: PaymentMarker): Judged;
+/**
+ * Change the marker of the attempt `attemptId` - record its signature or hash,
+ * or replace it with a retry's marker (same record, order and reference). Both
+ * the attempt and the record version must be the ones the caller judged: a
+ * signature recorded in between is never overrun.
+ */
+declare function judgeUpdateMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, attemptId: string, next: PaymentMarker): Judged;
+/**
+ * End the attempt `attemptId`, judged at `expectedVersion`: nothing was
+ * requested (`ordered`, the marker is removed), or the attempt provably ended
+ * (`ended-unpaid`, the marker is KEPT - it no longer excludes, but its floor,
+ * signature or hash is what later reconciliation starts from).
+ */
+declare function judgeClearMarker(records: readonly OrderRecord[], orderId: string, expectedVersion: number, attemptId: string, nextState: Extract<OrderState, 'ordered' | 'ended-unpaid'>): Judged;
+/**
+ * After a delivery: pin the store's owner, and add every payout of the offer
+ * that delivered to the known ones (pinning only the paid one would flag every
+ * other rail the store lists as changed next time). A delivery under a
+ * different owner than the pinned one never replaces the pin.
+ */
+declare function mergePins(current: StorePinsRecord | undefined, storePubkey: string, ownerPubkey: string, payouts: readonly {
+    caip19: string;
+    address: string;
+}[]): {
+    write?: StorePinsRecord;
+    result: StorePinsRecord;
+};
+/**
+ * The order records, over any `OrderBackend`. Every write that decides
+ * something about money is judged inside the backend's transaction and
+ * re-checks what the caller judged (the record version, the marker's attempt
+ * id), so a stale tab, a second process or a late wallet answer can never
+ * overrun a newer write.
+ */
+declare class OrderStore {
+    private readonly backend;
+    constructor(backend: OrderBackend);
+    /** Add a new order: `created`, version 1, no marker. Anything else is refused. */
+    add(record: OrderRecord): Promise<void>;
+    get(orderId: string): Promise<OrderRecord | undefined>;
+    /** Every record for a product, oldest first. */
+    forProduct(productAddress: string): Promise<OrderRecord[]>;
+    /** Run a rule on the product of `orderId` (it never changes), in one transaction. */
+    private judge;
+    /** Change plain fields of the record the caller judged at `expectedVersion`. */
+    update(orderId: string, expectedVersion: number, patch: RecordPatch): Promise<StoreWrite>;
+    /** See `judgeSetMarker`. */
+    setMarker(orderId: string, expectedVersion: number, marker: PaymentMarker): Promise<StoreWrite>;
+    /** See `judgeUpdateMarker`. */
+    updateMarker(orderId: string, expectedVersion: number, attemptId: string, next: PaymentMarker): Promise<StoreWrite>;
+    /** See `judgeClearMarker`. */
+    clearMarker(orderId: string, expectedVersion: number, attemptId: string, nextState: Extract<OrderState, 'ordered' | 'ended-unpaid'>): Promise<StoreWrite>;
+    pins(storePubkey: string): Promise<StorePinsRecord | undefined>;
+    /** See `mergePins`. */
+    rememberDelivery(storePubkey: string, ownerPubkey: string, payouts: readonly {
+        caip19: string;
+        address: string;
+    }[]): Promise<StorePinsRecord>;
+}
+/**
+ * An in-memory backend: for tests, and for a caller that keeps orders only for
+ * the life of the process. Transactions on it are trivially atomic (one thread).
+ */
+declare class MemoryOrderBackend implements OrderBackend {
+    private readonly orders;
+    private readonly stores;
+    read(orderId: string): Promise<OrderRecord | undefined>;
+    private snapshot;
+    forProduct(productAddress: string): Promise<OrderRecord[]>;
+    transactProduct<T>(productAddress: string, fn: (records: readonly OrderRecord[]) => {
+        write?: readonly OrderRecord[];
+        result: T;
+    }): Promise<T>;
+    readPins(storePubkey: string): Promise<StorePinsRecord | undefined>;
+    transactPins<T>(storePubkey: string, fn: (pins: StorePinsRecord | undefined) => {
+        write?: StorePinsRecord;
+        result: T;
+    }): Promise<T>;
+}
+
+type ReadyOffer$1 = Extract<LoadedOffer, {
+    ok: true;
+}>;
+/** The receipt `medium` of a chain: `solana`, `solana-devnet`, `tempo`, `tempo-moderato`. */
+declare function mediumOf(chain: Pick<ChainConfig, 'slug' | 'network'>): string;
+/**
+ * Whether the device clock is close enough to chain time to order: the rumor is
+ * dated by the chain, but the seal and the wrap by the device, and the widget
+ * drops a store status dated ahead of it - a slow clock would lose the delivery.
+ */
+declare function clockAgrees(chainTime: number, deviceTime: number): boolean;
+/**
+ * How a fresh offer compares with the one the buyer confirmed: the same payout
+ * and price and no new warning to confirm (`same`); something the buyer must
+ * look at again (`changed`); or the chosen payout is gone (`gone`).
+ */
+declare function compareOffers(shown: PricedPayout, confirmed: readonly OfferWarning[], fresh: ReadyOffer$1): 'same' | 'changed' | 'gone';
+interface PlaceOrderInput {
+    /** A FRESH verified offer (at most two minutes old). */
+    offer: ReadyOffer$1;
+    payout: PricedPayout;
+    email?: string;
+    /** Chain time read just before ordering (seconds). */
+    chainTime: number;
+    /** The device clock at the same moment (seconds). */
+    deviceTime: number;
+}
+interface OrderDeps {
+    store: OrderStore;
+    /** Reads (the offer, the inbox list): no key. */
+    readClient: RelayClient;
+    /**
+     * A NEW client for one order's writes, answering AUTH with its buyer key. The
+     * callee owns it and closes it when done, so it must never be one the caller
+     * also listens with.
+     */
+    clientFor: (buyerSecretKey: Uint8Array) => RelayClient;
+}
+type PlaceOrderResult = {
+    ok: true;
+    record: OrderRecord;
+} | {
+    ok: false;
+    reason: 
+    /** The device clock is too far from chain time. */
+    'clock_skew'
+    /** The offer is older than two minutes, or the payout is not one of its own: verify again. */
+     | 'stale_offer'
+    /** The store names no usable inbox relay: nowhere to send the order. */
+     | 'no_store_inbox'
+    /** The order went out but too few inbox relays took it; `resume` may try again. */
+     | 'not_acknowledged';
+    record?: OrderRecord;
+};
+/**
+ * Place a direct-mode order: a fresh one-time buyer key, a random order id, the
+ * reference derived from them, the order sealed and gift-wrapped to the store,
+ * recorded, then sent to the store's CURRENT inbox relays. It counts as placed
+ * only once enough of them said OK - the wallet opens only after that, since the
+ * merchant cannot attribute a payment without its order.
+ */
+declare function placeOrder(input: PlaceOrderInput, deps: OrderDeps): Promise<PlaceOrderResult>;
+/**
+ * The buyer's receipt (kind 17) once a payment went out: the medium, the derived
+ * reference and the transaction, sealed by the buyer key, recorded (for byte-for-
+ * byte republishing) and sent to the order's inbox relays.
+ */
+declare function sendReceipt(record: OrderRecord, tx: string, createdAt: number, deps: OrderDeps): Promise<StoreWrite>;
+/**
+ * On resume: read the store's inbox list again, and republish the SAME order and
+ * receipt wraps byte for byte to the union of its current inbox and the relays
+ * that took the order before (capped); a record not yet acknowledged may become
+ * so here. Returns the relays to listen on for the store's status.
+ */
+declare function resumeOrder(record: OrderRecord, deps: OrderDeps, now: number): Promise<{
+    record: OrderRecord;
+    relays: string[];
+}>;
+/**
+ * A store status for this record, or `undefined`: sealed by the store key, for
+ * this order id, naming this record's buyer key. Anything else - another
+ * sender, another order, another buyer - is not this order's answer.
+ */
+declare function statusFor(record: OrderRecord, wrap: NostrEvent): OrderStatusMessage | undefined;
+/** The delivery as a link, only when it is `https:`; anything else is shown as text. */
+declare function deliveryLink(value: string): string | undefined;
+/**
+ * Record a store status: the status itself (it only moves forward), and the
+ * state it settles - `completed` on delivery, `refunded` on a cancellation with
+ * a refund. The write retries on a concurrent change; a status the record can no
+ * longer take is left out.
+ */
+declare function applyStatus(store: OrderStore, orderId: string, message: OrderStatusMessage, at: number): Promise<OrderRecord | undefined>;
+/**
+ * Listen for the store's status on `relays`: gift wraps to the buyer key from
+ * the order's date back two days and the skew (NIP-59 back-dates wraps), each
+ * checked by `statusFor` before it is handed on. It listens with its own client
+ * that answers AUTH with the buyer key (inbox relays often ask for it before
+ * serving gift wraps), closed with the subscription.
+ */
+declare function listenForStatus(record: OrderRecord, relays: readonly string[], deps: Pick<OrderDeps, 'clientFor'>, onStatus: (message: OrderStatusMessage) => void): {
+    close(): void;
+};
+
+type ReadyOffer = Extract<LoadedOffer, {
+    ok: true;
+}>;
+/**
+ * A wallet account offering `solana:signTransaction`. The wallet signs the wire
+ * transaction the widget built and returns it; the widget sends it itself.
+ */
+interface SolanaWallet {
+    address: string;
+    signTransaction(transaction: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * What one payment attempt may spend, as the caller's spend limits count it:
+ * the coin's amount (for a token), and the SOL that leaves the payer's wallet
+ * (the fee, the payee's token-account rent when missing, `increment_stats`'
+ * rent on a new asset, and the amount itself for native SOL). The payer's own
+ * rent floor is only kept, never spent, so it is not counted.
+ */
+interface PaymentCosts {
+    asset: Asset;
+    /** Subunits of `asset` when it is a token; 0 for native SOL (counted in `lamports`). */
+    tokenAmount: bigint;
+    lamports: bigint;
+    /**
+     * The network fee inside `lamports`: the one part an attempt that never paid
+     * may still have spent (a transaction that landed and failed).
+     */
+    feeLamports: bigint;
+}
+interface SolanaPayDeps extends OrderDeps {
+    /** The widget's own Solana RPC. */
+    rpc: Rpc<SolanaRpcApi>;
+    /** The device clock (seconds); the receipt's date and the marker's `setAt`. */
+    now?: () => number;
+    newAttemptId?: () => string;
+    /**
+     * Whether `rpc` can prove an attempt over: a full-history endpoint whose
+     * "no payment" can be trusted. Without it (`false`) the watch never answers
+     * `over`, so nothing is retried or ended on an answer that could be wrong.
+     * The widget always has one (true, the default).
+     */
+    canProveOver?: boolean;
+    /**
+     * Called once an attempt's costs are known and before its marker is written;
+     * a throw refuses the payment with `spend_limit` before anything is recorded.
+     */
+    reserve?: (costs: PaymentCosts, attemptId: string) => void;
+    /** Called when the attempt `attemptId` was refused after `reserve`, before any broadcast. */
+    release?: (attemptId: string) => void;
+}
+interface PayInput {
+    /** A FRESH verified offer (at most two minutes old): the payout and price are checked against it. */
+    fresh: ReadyOffer;
+    /** Chain time read just before (seconds). */
+    chainTime: number;
+}
+type SolanaPayRefusal = 
+/** The record cannot take a payment now (state, no request, the store closed it). */
+'not_payable'
+/** The offer snapshot is older than two minutes: verify again. */
+ | 'stale_offer'
+/** The store no longer offers this payout at this price: end this order and start a new one. */
+ | 'offer_changed'
+/** Too close to the end of the merchant's catch-up: a new order instead. */
+ | 'too_late'
+/** The payer is the payout address itself (a transfer to oneself pays nothing). */
+ | 'self_payment' | 'insufficient_token' | 'insufficient_sol'
+/** A chain read failed; nothing was requested. */
+ | 'rpc_error'
+/** Another order for this product holds a live payment. */
+ | 'exclusion'
+/** The record changed meanwhile; read it again. */
+ | 'conflict'
+/** The wallet did not sign. The attempt stays live until its blockhash expires. */
+ | 'wallet_failed'
+/** The wallet returned a transaction the widget does not send (below). Same wait. */
+ | 'wallet_unsupported'
+/** A retry before the last attempt provably ended. */
+ | 'still_waiting' | 'already_paid'
+/** The caller's spend limit refused the attempt's costs (`reserve` threw). Nothing was recorded. */
+ | 'spend_limit';
+type SolanaPayResult = {
+    ok: true;
+    record: OrderRecord;
+    signature: string;
+} | {
+    ok: false;
+    reason: SolanaPayRefusal;
+    record?: OrderRecord;
+    /** For `exclusion`: the order holding it. */
+    holder?: string;
+    /** For `insufficient_*`: what the payment needs and what the payer has, in subunits / lamports. */
+    needed?: bigint;
+    available?: bigint;
+    /** For `wallet_unsupported`: what was wrong with the returned transaction. */
+    detail?: SignedRefusal;
+};
+/** The request stored on the record, as the schema reads it. */
+declare function storedSolanaRequest(record: OrderRecord): PaymentRequestData | undefined;
+/**
+ * Compose the order's payment request once, right after the order was
+ * acknowledged, from the order's own snapshot; resume and every verdict use this
+ * stored request, never a recomposed one.
+ */
+declare function composeOrderPayment(record: OrderRecord, store: OrderStore): Promise<StoreWrite>;
+/** What the payer holds and what the payment needs besides the fee itself. */
+interface Funds {
+    /** The payer's SOL, read before the marker. */
+    lamports: bigint;
+    /**
+     * Everything but the transaction fee the payer's SOL must cover: the payee's
+     * token-account rent when missing, `increment_stats`' rent on a new asset, the
+     * payer's own rent floor, and the amount itself for native SOL.
+     */
+    otherLamports: bigint;
+    /** The compute-unit price the widget asks (micro-lamports), for the payment's own accounts. */
+    priceMicroLamports: bigint;
+    /** What the attempt spends, for the caller's spend limits. */
+    costs: PaymentCosts;
+}
+type Checked = {
+    ok: true;
+    request: PaymentRequestData;
+    asset: Asset;
+    network: Network;
+    funds: Funds;
+} | Extract<SolanaPayResult, {
+    ok: false;
+}>;
+/**
+ * Every check that runs BEFORE the marker: nothing was requested if one fails.
+ * The fresh offer must still hold this payout at exactly the stored amount (a
+ * higher price cannot be accepted, a lower one would overpay).
+ */
+declare function checkBeforePaying(record: OrderRecord, payer: string, input: PayInput, deps: Pick<SolanaPayDeps, 'rpc' | 'now'>): Promise<Checked>;
+type SignedRefusal = 
+/** Not a transaction the widget can read. */
+'unreadable'
+/** Another blockhash, or a durable nonce (no expiry at all). */
+ | 'lifetime_changed'
+/** Another fee payer than the wallet account. */
+ | 'wrong_payer'
+/** A signature is missing or does not verify. */
+ | 'unsigned'
+/** The bound transfer is gone or pays another amount. */
+ | 'not_bound'
+/** A compute-budget setting twice: the runtime refuses the whole transaction. */
+ | 'duplicate_compute_budget';
+/**
+ * What the widget sends of a transaction the wallet returned: only one whose
+ * lifetime is exactly the attempt's blockhash (no durable nonce), paid by the
+ * wallet account, fully signed, with each compute-budget setting at most once,
+ * and whose bound transfer still pays exactly the stored amount - the same
+ * binding the merchant and "found" judge. It also returns the fee the
+ * transaction pays: a wallet may raise the price the widget set.
+ */
+declare function checkSignedTransaction(bytes: Uint8Array, expected: {
+    payer: string;
+    blockhash: string;
+    request: PaymentRequestData;
+    asset: Asset;
+}): Promise<{
+    ok: true;
+    signature: string;
+    wire: string;
+    feeLamports: bigint;
+} | {
+    ok: false;
+    reason: SignedRefusal;
+}>;
+/**
+ * The first payment of an acknowledged order: checks, the transaction, then the
+ * marker (test-and-set with the product's other orders) and only then the wallet.
+ */
+declare function payWithSolana(record: OrderRecord, wallet: SolanaWallet, input: PayInput, deps: SolanaPayDeps): Promise<SolanaPayResult>;
+type SolanaWatch = 
+/** The payment was found and recorded. */
+{
+    state: 'paid';
+    record: OrderRecord;
+}
+/** The attempt may still land, or the chain could not be read in full: keep watching. */
+ | {
+    state: 'waiting';
+    record: OrderRecord;
+}
+/** The attempt's blockhash expired at `finalized` and a full pass found no payment. */
+ | {
+    state: 'over';
+    record: OrderRecord;
+}
+/**
+ * The store delivered or refunded (a terminal record): its answer stands and
+ * nothing is left to watch. Says nothing about which transaction paid.
+ */
+ | {
+    state: 'closed';
+    record: OrderRecord;
+};
+/**
+ * One reconciliation step for a record with a Solana attempt: found -> paid;
+ * otherwise the signed bytes are sent again while the blockhash can land, and
+ * once it expired at `finalized` - read BEFORE the pass, together with its slot
+ * (the pass reads at least that far), so a pass that finds nothing proves it -
+ * a complete pass that finds nothing ends the attempt.
+ */
+declare function watchSolanaPayment(record: OrderRecord, deps: SolanaPayDeps): Promise<SolanaWatch>;
+/**
+ * A new attempt for the same order, reference and request, once the last one
+ * provably ended: the pass runs here, and the marker is replaced only at the
+ * version it judged (a payment found meanwhile is never overrun).
+ */
+declare function retryWithSolana(record: OrderRecord, wallet: SolanaWallet, input: PayInput, deps: SolanaPayDeps): Promise<SolanaPayResult>;
+/**
+ * End an order that will not be paid (the offer changed, the buyer starts over):
+ * at once when nothing was requested; with an attempt, only once it provably
+ * ended. `ended-unpaid` keeps the marker for later reconciliation.
+ */
+declare function endSolanaOrder(record: OrderRecord, deps: SolanaPayDeps): Promise<{
+    ended: boolean;
+    record: OrderRecord;
+}>;
+
+/**
+ * A wallet backed by a key in this process (the MCP's agent keypair): it signs
+ * exactly the wire transaction it is handed, and nothing else - the core checks
+ * the signed bytes as it does a browser wallet's.
+ */
+declare function localSolanaWallet(signer: KeyPairSigner): SolanaWallet;
+/** Chain time from a finalized block (the newest may not have its time yet), in seconds. */
+declare function readChainTime(rpc: Rpc<SolanaRpcApi>): Promise<number>;
+
+/**
+ * Decisions a purchase makes about the records it holds, shared by the widget's
+ * session and the MCP's tools. Each caller sequences them with its own screens
+ * or answers; the rules are the same.
+ */
+/** The store cancelled an order no payment is known for (the attempt, if any, is over). */
+declare function cancelledUnpaid(record: OrderRecord): boolean;
+/** Ended with no payment found (by this caller or another): no longer this product's purchase. */
+declare function gone(record: OrderRecord): boolean;
+/**
+ * Whether `record` can still be paid on `payout`: an order is placed for one
+ * payout and price, so an order on other terms, or one the store cancelled
+ * while unpaid, must end before a new one is placed.
+ */
+declare function onOtherTerms(record: OrderRecord, payout: PricedPayout): boolean;
+type EndDeps = Pick<SolanaPayDeps, 'store' | 'readClient' | 'clientFor' | 'now' | 'canProveOver'> & {
+    /** The order's own network's RPC, or `undefined` when the caller has none for it. */
+    rpc: SolanaPayDeps['rpc'] | undefined;
+    store: OrderStore;
+};
+/**
+ * End an order that will not be paid, before a new one is placed beside it:
+ * - a `created` order was never acknowledged and holds nothing: it counts as
+ *   ended at once (it is never moved; `created` only becomes `ordered`);
+ * - an acknowledged order with no attempt ends through the store alone;
+ * - an order with an attempt ends only once the attempt provably ended, which
+ *   needs the order's own RPC and `canProveOver` (see `endSolanaOrder`).
+ * `ended: false` means an attempt may still land: follow it, never place a
+ * second order beside it.
+ */
+declare function endOrder(record: OrderRecord, deps: EndDeps): Promise<{
+    ended: boolean;
+    record: OrderRecord;
+}>;
+
+export { type AuthSigner, CONFIRM_WARNINGS, DEFAULT_RELAYS, type EndDeps, type LoadOfferOptions, type LoadedOffer, MAX_CLOCK_SKEW_SECS, MAX_RELAY_URL_LENGTH, MERCHANT_CATCH_UP_SECS, MemoryOrderBackend, OFFER_SNAPSHOT_MAX_AGE_SECS, ORDER_ACK_TARGET, type OrderBackend, type OrderDeps, type OrderRecord, type OrderState, type OrderStatus, OrderStore, PAYMENT_SCAN_MARGIN_SECS, PAY_CUTOFF_SECS, type PayInput, type PaymentCosts, type PaymentMarker, type PlaceOrderInput, type PlaceOrderResult, type PoolLike, type PricedPayout, type PublishResult, RELAY_CONNECT_MAX_WAIT_MS, RELAY_PUBLISH_DEADLINE_MS, RELAY_QUERY_DEADLINE_MS, RELAY_QUERY_MAX_WAIT_MS, type RecordPatch, type RelayClient, type RelayClientOptions, type RelayLike, SOLANA_COMPUTE_UNIT_LIMIT, STORE_RELAY_CAP, STORE_WRITE_ATTEMPTS, SUBSCRIBE_RETRY_MAX_MS, SUBSCRIBE_RETRY_MS, SUBSCRIBE_STABLE_MS, type SignedRefusal, type SolanaPayDeps, type SolanaPayRefusal, type SolanaPayResult, type SolanaWallet, type SolanaWatch, type StoreInbox, type StorePins, type StorePinsRecord, type StoreRelaySources, type StoreWrite, TERMINAL_STATES, WRAP_BACKDATE_SECS, type WidgetRefusal, applyStatus, cancelledUnpaid, checkBeforePaying, checkSignedTransaction, clockAgrees, compareOffers, composeOrderPayment, createPool, createRelayClient, deliveryLink, endOrder, endSolanaOrder, gone, holdsPayExclusion, isEventShaped, isGenuineEvent, isPageOrigin, isSnapshotStale, isTerminal, judgeAdd, judgeClearMarker, judgeSetMarker, judgeUpdate, judgeUpdateMarker, listenForStatus, loadOffer, loadOfferForAgent, localSolanaWallet, mediumOf, mergePins, newestGenuine, newestStoreInbox, normalizeRelayUrl, nowSecs, onOtherTerms, payWithSolana, placeOrder, readChainTime, readRelays, readStoreInbox, recordToShow, relayHost, resumeOrder, retryWithSolana, sendReceipt, statusFor, storeRelays, storedSolanaRequest, uniqueRelays, watchSolanaPayment };