import { type Keyset } from "./denom.js"; /** * The most bytes this wallet puts in one `X-PAYMENT` header by default: * 7.5 KiB, 7,680 bytes. * * Under {@link NGINX_DEFAULT_HEADER_LINE_BYTES} for the header's own line * (`X-PAYMENT: ` and the value), and 8.5 KiB under * {@link NODE_DEFAULT_MAX_HEADER_BYTES} for the request line and every other * header the request carries. 7,680 bytes of base64 are 5,760 of JSON; a * launch-ladder coin is 576 of them and the envelope `348 + url`, so nine * coins fit with a resource URL of up to 228 bytes, and ten never do (module * docs). A price whose cover needs more coins is paid in fewer, with one * larger coin split and its residual refreshed. * * Configurable (`WalletConfig.maxPaymentHeaderBytes`, * `WrapFetchOptions.maxHeaderBytes`) when every merchant a wallet pays takes * larger headers; 12,288 bytes reaches the facilitator's fifteen-coin cap, * and a larger value buys nothing past it. */ export declare const DEFAULT_MAX_PAYMENT_HEADER_BYTES = 7680; /** * nginx's default `large_client_header_buffers 4 8k`: the longest single * request header line (name, `: `, value) an nginx in front of a merchant * accepts before it answers `400`. Documentation, not configuration. */ export declare const NGINX_DEFAULT_HEADER_LINE_BYTES: number; /** * Node's default `--max-http-header-size`: the whole request header section * a merchant running Node accepts before it answers `431`. Documentation, not * configuration -- a merchant's limit is the merchant's. */ export declare const NODE_DEFAULT_MAX_HEADER_BYTES: number; /** * The resource URL length, in bytes, a capacity estimate assumes when it has * no URL in hand ({@link maxCoinsWithinHeaderBudget}). A payment always * measures its own URL; this only sizes the wallet's answer to "how many * coins can one payment carry?" before there is a payment. */ export declare const REFERENCE_RESOURCE_URL_BYTES = 128; /** One coin's entry in `payload.coins` (§11), member order as sent. */ export interface WireCoin { readonly denomId: string; /** Base64 `C_p`. */ readonly coinPub: string; /** Base64 `σ`, `L = bitlen(N)/8` bytes before encoding (§6.12). */ readonly denomSig: string; /** `f`, a decimal string (§6.14). */ readonly fraction: string; /** Base64 deposit permission, 64 bytes before encoding. */ readonly depositSig: string; /** * The keyset this coin is drawn from, `0x`-prefixed -- present only when * it is not the payload's `keysetId` (K1; see the module docs). */ readonly keysetId?: string; } /** `PaymentPayload.payload`: the px402 binding's own body (§11). */ export interface Px402Payload { readonly px402Version: number; readonly keysetId: string; readonly coins: readonly WireCoin[]; readonly nonce: string; readonly validUntil: number; readonly termsSalt: string; } /** x402's `PaymentPayload`, as this wallet sends it (§11). */ export interface PaymentPayload { readonly x402Version: number; readonly scheme: string; readonly network: string; readonly resource: { readonly url: string; }; readonly payload: Px402Payload; } /** * The fields a coin entry is built from, as {@link wireCoin} and * {@link coinEntryBytes} both read them -- the second without a signature, * because selection sizes a payment before anything is signed. */ export interface CoinShape { readonly coin: { readonly denomId: string; readonly pub: Uint8Array; readonly sigma: Uint8Array; }; readonly fraction: bigint; /** * The coin's own keyset, `0x`-prefixed, when the caller knows it (K1). * Omitted: the payload's. */ readonly keysetId?: string | undefined; } /** * Which keyset a payment's payload names, and which of its coins carry a * `keysetId` of their own (K1). * * `coinKeysets[i]` is coin `i`'s keyset (`undefined`: `fallback`'s). The * payload names the keyset the most coins share among those `eligible` may * name -- the payload's keyset is also the one whose smallest rung the fee * was rounded to (v3 §25.1), so only a keyset with that rung qualifies -- * with ties going to `fallback`, then to the lowest id, so the plan is a * function of the coins. With none eligible, `fallback`. Every coin of * another keyset is tagged. */ export declare function planKeysetTags(coinKeysets: readonly (string | undefined)[], fallback: string, eligible?: (keysetId: string) => boolean): { readonly payloadKeysetId: string; readonly tags: readonly (string | undefined)[]; }; /** Standard, padded base64 (RFC 4648 §4): what x402 and §11 carry. */ export declare function base64(bytes: Uint8Array): string; /** The length of {@link base64} of `n` bytes: `4 × ceil(n / 3)`. */ export declare function base64Length(n: number): number; /** * Base64 to bytes, refusing anything that is not base64 rather than guessing. * * Reads what x402 headers carry back to a wallet -- a `SettleResponse` in * `X-PAYMENT-RESPONSE`, an x402 v2 `PAYMENT-REQUIRED` -- so it throws a * `RangeError` on a character outside the standard alphabet; the caller * decides what an unreadable header means. */ export declare function base64Decode(value: string): Uint8Array; /** `base64(UTF-8(JSON.stringify(value)))`: an x402 header value. */ export declare function base64Json(value: unknown): string; /** * The JSON inside an x402 header value, or `undefined` when it is not * base64 of UTF-8 JSON. (JSON has no `undefined`, so the two never collide.) */ export declare function decodeBase64Json(value: string): unknown; /** * A signed coin's wire entry (§11), with its own `keysetId` when `tag` names * one ({@link planKeysetTags}). */ export declare function wireCoin(part: CoinShape & { readonly depositSig: Uint8Array; }, tag?: string): WireCoin; /** * The JSON bytes one coin's entry will take, before it is signed. * * Exact, not estimated: the entry is built by the same function the real one * is, with each base64 member replaced by a placeholder of its encoded * length -- the lengths depend only on the byte counts, which are known. */ export declare function coinEntryBytes(part: CoinShape, tag?: string): number; /** The `X-PAYMENT` header value: base64 of the payload's UTF-8 JSON (§11). */ export declare function encodePaymentHeader(payload: PaymentPayload): string; /** * The exact size of the `X-PAYMENT` header a payment would carry, for any * choice of coins -- so selection can plan inside the budget before it * signs or retires anything. * * `envelope` is the payload with everything but its coins filled in; its * `coins` are ignored. The answer for a selection equals * `encodePaymentHeader(...).length` for the payload those coins complete, * byte for byte (`payload.test.ts`). * * Coins of several keysets (K1) are sized as {@link planKeysetTags} plans * them, against `envelope.payload.keysetId` and `eligible`: a coin tagged * with its own keyset costs its tag. Every keyset id is the same width, so * which one the payload names does not change the envelope's size. */ export declare function paymentHeaderSizer(envelope: PaymentPayload, eligible?: (keysetId: string) => boolean): (parts: readonly CoinShape[]) => number; /** * How many coins one payment can carry inside `maxHeaderBytes` under * `keyset`, for a resource URL of `resourceUrlBytes`. * * Every coin is sized as the keyset's **largest** denomination -- the longest * `denomId` and `fraction`, and the widest `σ` -- so the answer is a floor: a * real payment of smaller coins fits at least this many. The envelope takes * the widest members a payment can have (a 32-byte nonce, a ten-digit * `validUntil`, a two-digit x402 version, a CAIP-2 network of 24 characters). * What a wallet uses before it has a payment to measure; the spend path * measures the payment itself. * * `tagged` sizes every coin with a `keysetId` of its own (K1): the floor for * a wallet holding coins of more than one epoch, whose payment may tag some. */ export declare function maxCoinsWithinHeaderBudget(maxHeaderBytes: number, keyset: Keyset, resourceUrlBytes?: number, tagged?: boolean): number;