/** * `GET /supported` (x402 v2 §11; px402 v3 §7): what a facilitator will * settle, through whom, and — the part the wallet acts on — for what fee. * * # The fee is the facilitator's, and it is one number * * v3 opens the relayer set. Each relayer advertises its own `feeBps` on * chain, but the wallet does not choose a relayer and cannot know which one * the facilitator will lease (§8 picks at random, weighted by performance, * precisely so that the choice is not a signal). What the wallet needs is * one figure it can present against, and that is `kinds[i].extra.feeBps`: * the **uniform** fee this facilitator charges for a payment on this * network. The payer presents `price + ceil(price × feeBps / 10 000)`, * **rounded up to a whole number of the smallest denomination** of the * keyset in force (v3 §25.1), in coins; the merchant receives `price`; the * difference -- the rate's fee plus the rounding overage -- is the relayer's * revenue. The per-relayer list beside it is disclosure, not an input. * * # Why the presented total is rounded to the ladder * * Before §25.1 the presented total was `price + ceil(price × feeBps / 10⁴)`, * which is almost never a whole number of the smallest rung: a $0.003 call at * 100 bps presented 3 030 base units, and whatever coin covered it left a * residual of 970 -- below the $0.001 rung, so no melt could mint it and it * sat in the wallet as dust until recoup (§6.9), which reveals the coin's * issuance. Rounded, * the same call presents 4 000: an exact cover exists at any fee, no dust * coin is ever made, and the payer pays the overage to the relayer instead of * stranding it. With `feeBps = 0` nothing is rounded: `presented = price`, * exactly as before fees existed. * * The smallest rung is read from the wallet's own keyset, never assumed: * ladders are per epoch. A facilitator that charges a fee names the rule in * `extra.feeRounding` ({@link FEE_ROUNDING_RULE}); one that charges a fee and * names no rule this wallet knows is refused before any coin is presented, * because it would refuse the rounded total at `/verify` after §7 had already * retired the coins. * * # Fail closed, and say why * * Every path that cannot establish the fee ends in {@link PX402FeeError} * rather than in a default. A wallet that assumed 0 against a facilitator * charging 25 bps would present `price`, fail `INSUFFICIENT_VALUE` at * `/verify`, and have already retired its coins under §7 for nothing; a * wallet that assumed the maximum would overpay silently. The one default * this module does take is the **v2** shape — a single signer address and no * fee member — which was specified before fees existed and can only mean 0. * The version is read from the shape of `signers[network]` (a string is v2, a * list is v3), never from a version field the older facilitator does not have. * * # Cached per facilitator, on the wallet's clock * * A wallet pays the same few facilitators repeatedly, and `/supported` is a * static document that changes when the operator changes it. So it is fetched * once per facilitator URL and kept for {@link DEFAULT_SUPPORTED_TTL_SECONDS}, * measured on the same injected clock everything else in the SDK runs on. A * refusal is never cached: the next payment asks again, so an outage costs one * failed payment per attempt rather than five minutes of them. */ import { type FetchLike } from "./client.js"; /** Basis points in a whole: `fee = ceil(price × feeBps / 10 000)`. */ export declare const BPS_DENOMINATOR = 10000n; /** * The fee-rounding rule a facilitator names in `/supported`'s * `kinds[i].extra.feeRounding` (v3 §25.1): the presented total is * `price + ceil(price × feeBps / 10 000)` rounded up to a whole number of the * smallest denomination of the keyset the payment's coins are drawn from. */ export declare const FEE_ROUNDING_RULE = "smallest-denomination"; /** * The wallet's default ceiling on a fee it will pay: the protocol's launch * `MAX_FEE_BPS` (v3 §5, §14), 1 %. A facilitator quoting more is refused * with {@link PX402FeeError} rather than paid. */ export declare const DEFAULT_MAX_FEE_BPS = 100; /** How long a fetched `/supported` is trusted before it is re-read. */ export declare const DEFAULT_SUPPORTED_TTL_SECONDS = 300; /** One relayer the facilitator routes to, as `/supported` advertises it. */ export interface SupportedRelayer { /** The on-chain registration, `0x`-prefixed; `null` for a pinned relayer. */ readonly address: string | null; /** This relayer's own advertised fee. Disclosure: the wallet pays {@link FacilitatorSupport.feeBps}. */ readonly feeBps: number; /** `bond / rolling24hRedeemed` from its `/solvency`, or `null`. */ readonly relayerCoverageRatio: string | null; /** Its EIP-3009 payout address, or `null` if not yet read. */ readonly payoutAddress: string | null; /** * The tokens it fronts under the exact-scheme bridge (v3 §26.3, §26.4), as * `extra.relayers[i].bridgeAssets` lists them; `null` when the facilitator * names none. Disclosure: the wallet pays through {@link FacilitatorSupport.bridgeAssets}. */ readonly bridgeAssets: readonly string[] | null; } /** Which `/supported` shape was read; see the module docs. */ export type SupportedVersion = 2 | 3; /** A facilitator's `/supported`, read for one network. */ export interface FacilitatorSupport { /** The facilitator URL this was fetched from, as the requirements named it. */ readonly facilitator: string; readonly network: string; readonly version: SupportedVersion; /** The uniform, payer-paid fee in basis points (v3 §7). `0` under v2. */ readonly feeBps: number; /** * `extra.feeRounding`: the rule the presented total is rounded by (v3 * §25.1), or `null` when the facilitator names none -- which is accepted * only at a fee of zero, where nothing is rounded. */ readonly feeRounding: string | null; readonly relayers: readonly SupportedRelayer[]; /** * `extra.bridge.assets`: the tokens this facilitator pays a merchant's * `exact` requirements in, through a relayer's EIP-3009 authorization (v3 * §26.3). Empty when it does not bridge -- `extra.bridge` absent -- which * is every facilitator before §26. */ readonly bridgeAssets: readonly string[]; /** * `extra.bridge.networks` (v3 §28.5): every network this facilitator pays a * merchant's `exact` requirements on, its own included, each with the * tokens it pays in there, lower-cased. A facilitator that names no map * pays on its own network alone: `{ [network]: bridgeAssets }`, or `{}` * when it does not bridge. Keyed by CAIP-2 (`eip155:8453`). */ readonly bridgeNetworks: Readonly>; /** The payout addresses Tier 0 settlements arrive from, one per relayer. */ readonly signers: readonly string[]; /** The v2 aggregate: the minimum coverage across the set, or `null`. */ readonly relayerCoverageRatio: string | null; /** Unix seconds on the wallet's clock, for the cache's TTL. */ readonly fetchedAt: number; } /** What a payer presents for a price under a fee. */ export interface PresentedAmount { readonly price: bigint; /** * `presented − price`: the rate's `ceil(price × feeBps / 10 000)` plus the * rounding overage up to the smallest denomination (v3 §25.1). All of it is * the relayer's; the merchant receives `price`. */ readonly fee: bigint; /** `price + fee`: what the coins must cover and what `ContractTerms.amount` carries. */ readonly presented: bigint; } /** * `ceil(price × feeBps / 10 000)` in `bigint`, so a price beyond 2^53 base * units is charged exactly rather than rounded on the way through a double. * * Rounded **up**: the relayer is paid a whole base unit for any fraction of * one, which is the direction a fee owed rounds. `price 1, 1 bps` is a fee of * 1; `price 10 000, 25 bps` is exactly 25. */ export declare function relayerFee(price: bigint, feeBps: number): bigint; /** `ceil(value / step) × step`: the least whole number of `step`s at or above `value`. */ export declare function roundUpTo(value: bigint, step: bigint): bigint; /** * The price, its fee under `feeBps`, and their sum (v3 §25.1): * * ```text * presented = price if feeBps = 0 * presented = roundUp(price + ceil(price × feeBps / 10 000), smallest) otherwise * fee = presented − price * ``` * * `smallestDenomination` is the smallest rung of the keyset the coins are * drawn from, read from that keyset -- never a constant, because ladders are * per epoch. At a fee of zero nothing is rounded: a facilitator that charges * nothing has no fee to absorb an overage, and the payment is byte for byte * the one made before fees existed. */ export declare function presentedAmount(price: bigint, feeBps: number, smallestDenomination: bigint): PresentedAmount; /** * The most a payment of `price` can cost in fee when the rate is at most * `maxFeeBps`: `ceil(price × maxFeeBps / 10 000) + smallestDenomination − 1` * (v3 §25.1). The rounding can add at most one rung less a base unit, so this * is the bound {@link presentedAmount} never exceeds at any rate up to * `maxFeeBps` -- and the relayer's own cap, at the contract's `MAX_FEE_BPS`. * A ceiling of zero admits no fee at all, and so no rounding either. */ export declare function feeCeiling(price: bigint, maxFeeBps: number, smallestDenomination: bigint): bigint; /** * Whether a bridge map ({@link FacilitatorSupport.bridgeNetworks}) lists the * pair *(network, asset)* (v3 §28.2): the network exactly, the address in * any case. */ export declare function bridgesPair(networks: Readonly>, network: string, asset: string): boolean; /** * Read a `/supported` body for one network. Pure: the caller fetched it. * * @throws PX402FeeError `"malformed"`, `"unsupported"`, `"fee-missing"` or * `"fee-rule-unknown"`; see {@link FeeRefusal} and the module docs for which * shape yields which. */ export declare function parseSupported(body: unknown, params: { readonly facilitator: string; readonly network: string; readonly fetchedAt: number; }): FacilitatorSupport; /** * The fee this wallet will pay, or a refusal. * * Returns `support.feeBps` when it is at or under `maxFeeBps` (default * {@link DEFAULT_MAX_FEE_BPS}); throws {@link PX402FeeError} `"fee-over-max"` * naming the facilitator, the fee and the ceiling otherwise. */ export declare function checkFee(support: FacilitatorSupport, maxFeeBps?: number): number; /** A presented total, with the rate it was quoted at. */ export interface Quote extends PresentedAmount { /** The facilitator's advertised rate, in basis points. */ readonly feeBps: number; } /** * What this wallet presents for `price` through this facilitator, or a * refusal (v3 §7, §25.1). * * Two bounds, both carried by the {@link PX402FeeError} `"fee-over-max"` it * throws: the **rate** (`support.feeBps ≤ maxFeeBps`, as {@link checkFee}), * and the **amount** -- the fee on this price, rounding included, never above * {@link feeCeiling}`(price, maxFeeBps, smallestDenomination)`. The second * follows from the first by construction; it is checked anyway, so a wallet * never presents a fee it has not bounded in base units, and the refusal * names both what the payment would have cost and what the wallet allows. */ export declare function quotePayment(price: bigint, support: FacilitatorSupport, options: { readonly maxFeeBps?: number; readonly smallestDenomination: bigint; }): Quote; /** Options for {@link SupportedCache}. */ export interface SupportedCacheOptions { /** Unix seconds. Defaults to the system clock. */ readonly now?: () => number; /** Defaults to {@link DEFAULT_SUPPORTED_TTL_SECONDS}. `0` re-reads on every lookup. */ readonly ttlSeconds?: number; } /** What one {@link SupportedCache.lookup} needs. */ export interface SupportedLookup { /** The facilitator URL the merchant's requirements named (`extra.facilitator`). */ readonly facilitator: string; readonly network: string; /** The `fetch` to read it with. Injected so a wallet opens no sockets of its own. */ readonly fetch: FetchLike; } /** * A per-facilitator cache of {@link FacilitatorSupport}, with a TTL on the * wallet's clock. One per wallet; see the module docs for why a refusal is * never cached. */ export declare class SupportedCache { private readonly entries; private readonly now; private readonly ttlSeconds; constructor(options?: SupportedCacheOptions); /** * This facilitator's support for this network, from cache when it is * fresh, otherwise from `GET {facilitator}/supported`. * * @throws PX402FeeError on any path that does not yield a fee; see * {@link FeeRefusal}. */ lookup(params: SupportedLookup): Promise; /** Forget one facilitator's entry, or every entry. */ invalidate(facilitator?: string): void; private read; }