import type { FetchLike, ServiceAnswer } from "./client.js"; import { type ContractTerms } from "./terms.js"; /** x402 v2's 402 header: base64 of the whole `PaymentRequired` document. */ export declare const PAYMENT_REQUIRED_HEADER = "PAYMENT-REQUIRED"; /** x402 v2's payment header: base64 of the `PaymentPayload` (`accepted`, `resource`, `payload`). */ export declare const PAYMENT_SIGNATURE_HEADER = "PAYMENT-SIGNATURE"; /** x402 v2's settlement header, the counterpart of v1's `X-PAYMENT-RESPONSE`. */ export declare const PAYMENT_RESPONSE_V2_HEADER = "PAYMENT-RESPONSE"; /** The x402 scheme the bridge pays. */ export declare const EXACT_SCHEME = "exact"; /** * x402 v1 names a network; px402 speaks CAIP-2. Only these are mapped * (§26.8 step 1, §28.7): a name not here is a network the bridge does not pay on. */ export declare const X402_NETWORK_NAMES: ReadonlyMap; /** * The longest an authorization may live (§26.3): `validUntil` and the * relayer's `authorization_ttl` are `min(maxTimeoutSeconds, 3600)`. */ export declare const BRIDGE_MAX_TIMEOUT_SECONDS = 3600; /** * The shortest `min(maxTimeoutSeconds, 3600)` the bridge pays under (§26.4): * the facilitator refuses less `BRIDGE_TIMEOUT_TOO_SHORT`, and the wallet * refuses first, before anything is sent. */ export declare const BRIDGE_MIN_TIMEOUT_SECONDS = 120; /** An authorization must outlive the wallet's clock by more than this to be delivered. */ export declare const VALID_BEFORE_MARGIN_SECONDS = 10; /** * The most times the wallet delivers one authorization (§26.8 step 5): once, * and twice more while the merchant answers 402 to it. */ export declare const BRIDGE_DELIVERY_ATTEMPTS = 3; /** * The pause before a delivery is sent again, in milliseconds: this, plus up * to {@link BRIDGE_REDELIVERY_JITTER_MS} drawn afresh each time. */ export declare const BRIDGE_REDELIVERY_PAUSE_MS = 1000; /** The random part of the pause before a delivery is sent again, in milliseconds. */ export declare const BRIDGE_REDELIVERY_JITTER_MS = 1000; /** * An authorization is delivered again only while its `validBefore` is at * least this many seconds past the wallet's clock as the request goes out: * room for the merchant's facilitator to check it, send it and have it in a * block before the token stops accepting it. */ export declare const REDELIVERY_MARGIN_SECONDS = 30; /** The registry's `LEASE_TTL` (v3 §4): how long a relayer's lease runs. */ export declare const LEASE_TTL_SECONDS = 60; /** `RECORD_GRACE` (v3 §4): how long after its lease a relayer may record a payout. */ export declare const RECORD_GRACE_SECONDS = 3600; /** `PAYOUT_DEADLINE` (v3 §18.6): the dispute window, and the cancel fallback's wait (§20.2). */ export declare const PAYOUT_DEADLINE_SECONDS = 86400; /** The EIP-712 domain type of an EIP-3009 token (Circle's FiatTokenV2). */ export declare const EIP712_DOMAIN_TYPE = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"; /** EIP-3009's struct, character for character as FiatTokenV2 hashes it. */ export declare const TRANSFER_WITH_AUTHORIZATION_TYPE = "TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"; /** Two `0x` addresses are one address whatever their case (EIP-55 is a checksum, not an identity). */ export declare function sameAddress(a: string, b: string): boolean; /** A network as served, in CAIP-2; `undefined` for one the bridge does not pay on. */ export declare function caip2Network(network: string): string | undefined; /** One `exact` entry of a 402, checked, with the entry kept as served. */ export interface ExactEntry { /** * The entry exactly as the merchant served it: hashed into `acceptedHash`, * posted to the bridge facilitator as `paymentRequirements`, and echoed to * a v2 merchant as `accepted`. Never edited. */ readonly raw: Record; /** The merchant's x402 version: it enters the terms (§26.2) and picks the header. */ readonly x402Version: 1 | 2; /** `network` as served: a name under v1 (`base`), CAIP-2 under v2. */ readonly network: string; /** The same network in CAIP-2 (`eip155:8453`). */ readonly caip2: string; /** The EIP-155 chain id, for the token's EIP-712 domain. */ readonly chainId: bigint; /** The token the merchant is paid in, `0x`-prefixed as served. */ readonly asset: string; readonly payTo: string; /** * The price, in the asset's base units: `amount` (v2) or * `maxAmountRequired` (v1). What the merchant receives and the * authorization's `value`. */ readonly price: bigint; readonly maxTimeoutSeconds: number; /** `extra.name`: the token's EIP-712 domain name (`"USD Coin"` for USDC on Base). */ readonly name: string; /** `extra.version`: the token's EIP-712 domain version (`"2"`). */ readonly version: string; } /** What a 402 asks for, as far as the bridge is concerned. */ export interface PaymentRequired { readonly x402Version: 1 | 2; /** Every well-formed `exact` entry, in the merchant's order. */ readonly exact: readonly ExactEntry[]; /** * Whether the 402 also offers px402 (`batch-settlement`, `extra.binding: * "px402"`). Then the bridge stays out: the merchant takes coins directly. */ readonly offersPx402: boolean; /** x402 v2's `resource.url`, when the merchant served one. */ readonly resourceUrl: string | undefined; } /** * The requirements of a 402: the base64 `PAYMENT-REQUIRED` header (x402 v2) * when it carries a readable document, else the JSON body's `accepts[]` * (v1 or v2). `undefined` when neither is one. * * Under v1 the network is a name and the price `maxAmountRequired`; under v2 * the network is CAIP-2 and the price `amount`. An entry carrying both price * members with different values is skipped, as is any entry missing one of * `network`, `asset`, `payTo`, a price, `maxTimeoutSeconds`, `extra.name` or * `extra.version`: the wallet cannot pay what it cannot read exactly. */ export declare function parsePaymentRequired(body: unknown, header: string | null): PaymentRequired | undefined; /** * How long this payment's terms and authorization may live: * `min(maxTimeoutSeconds, 3600)` (§26.2, §26.3). */ export declare function bridgeTimeoutSeconds(entry: ExactEntry): number; /** An EIP-3009 token's EIP-712 domain. */ export interface TokenDomain { readonly name: string; readonly version: string; readonly chainId: bigint; /** The token's address, `0x`-prefixed. */ readonly verifyingContract: string; } /** * An EIP-3009 `TransferWithAuthorization`, as x402 carries it: every member a * string -- addresses and the nonce `0x`-prefixed hex, the three integers * decimal. */ export interface TransferAuthorization { readonly from: string; readonly to: string; readonly value: string; readonly validAfter: string; readonly validBefore: string; readonly nonce: string; } /** * `keccak256(abi.encode(EIP712Domain typehash, keccak(name), keccak(version), * chainId, verifyingContract))` -- what the token's `DOMAIN_SEPARATOR()` * returns when the domain is right. Pinned in `bridge.test.ts` against the * value Circle's USDC returns on Base. */ export declare function tokenDomainSeparator(domain: TokenDomain): Uint8Array; /** EIP-712's `hashStruct` of a {@link TransferAuthorization}. */ export declare function transferWithAuthorizationStructHash(a: TransferAuthorization): Uint8Array; /** * The digest the relayer signs and the token's `ecrecover` checks: * `keccak256("\x19\x01" ‖ domainSeparator ‖ hashStruct(authorization))` -- * the relayer's `transfer_with_authorization_digest`, rebuilt here. */ export declare function transferWithAuthorizationDigest(domainSeparator: Uint8Array, a: TransferAuthorization): Uint8Array; /** * The address a 65-byte `r ‖ s ‖ v` signature over `digest` recovers to, * lowercase and `0x`-prefixed; `undefined` for a signature `ecrecover` would * not accept -- `v` other than 27 or 28, `r` or `s` out of range, or a * high-`s` copy, which FiatTokenV2's `ECRecover` refuses. */ export declare function recoverAuthorizationSigner(digest: Uint8Array, signature: string): string | undefined; /** `SettleResponse.extra.bridge` (§26.3), read. */ export interface BridgeAnswer { /** The token the relayer authorized, as the facilitator reports it. */ readonly asset: string; /** The relayer the facilitator handed the payment to, when it says. */ readonly relayer: string | undefined; readonly authorization: TransferAuthorization; /** 65 bytes, `0x`-prefixed hex, `r ‖ s ‖ v`. */ readonly signature: string; } /** * `extra.bridge` as a {@link BridgeAnswer}, or `undefined` when it is not one: * every member present, addresses and the nonce in `0x` hex, the three * integers decimal strings, the signature 65 bytes. */ export declare function parseBridgeAnswer(value: unknown): BridgeAnswer | undefined; /** What {@link checkBridgeAnswer} checks an answer against. */ export interface BridgeCheck { readonly facilitator: string; /** The entry the payment's terms were built over. */ readonly entry: ExactEntry; /** The payment's terms: the source of `payoutNonce`. */ readonly terms: ContractTerms; /** Unix seconds, the wallet's clock. */ readonly now: number; /** Every relayer payout address the bridge facilitator's `/supported` lists. */ readonly payoutAddresses: readonly string[]; } /** * §26.8 step 4 and §26.12, in order: `to`, `value`, `validAfter`, * `validBefore`, `nonce`, `asset`, `from`, the signature. Returns nothing; a * failed check throws {@link PX402BridgeError} whose `reason` names it. * * The messages name the check, never the addresses or the nonce: an error is * what reaches a log, and these values join the payer to the merchant. */ export declare function checkBridgeAnswer(answer: BridgeAnswer, check: BridgeCheck): void; /** Every relayer payout address a `/supported` lists. */ export declare function payoutAddressesOf(relayers: readonly { readonly payoutAddress: string | null; }[]): string[]; /** One request header: what the wallet adds to the re-issued request. */ export interface DeliveryHeader { readonly name: string; readonly value: string; } /** * The header that delivers the authorization to the merchant (§26.8 step 5): * * - v1: `X-PAYMENT` = base64 `{ x402Version: 1, scheme: "exact", network: * , payload: { signature, authorization } }`; * - v2: `PAYMENT-SIGNATURE` = base64 `{ x402Version: 2, accepted: , resource: { url }, payload: { signature, authorization } }`. * * `resourceUrl` is the v2 document's `resource.url` when the merchant served * one, else the URL the wallet fetched. */ export declare function exactPaymentHeader(entry: ExactEntry, answer: BridgeAnswer, resourceUrl: string): DeliveryHeader; /** * Whether an authorization the merchant answered 402 to is delivered again * when `at` comes (unix seconds, the wallet's clock -- the clock step 4's * `validBefore` check reads): only while at least * {@link REDELIVERY_MARGIN_SECONDS} of it are left then (§26.8 step 5). * * Sending it again cannot pay twice: the token accepts an authorization's * nonce once, so a second delivery either settles the payment the first did * not or is refused. What it fixes is a merchant whose own facilitator failed * to send a valid authorization -- a busy hot wallet, a lost nonce, an RPC * that refused -- and answered 402 with the authorization still unused. */ export declare function redeliverable(authorization: TransferAuthorization, at: number): boolean; /** The merchant's settlement answer (`X-PAYMENT-RESPONSE` / `PAYMENT-RESPONSE`). */ export interface MerchantSettlement { /** `true` only for a readable answer saying `success: true`. */ readonly success: boolean; /** The settlement transaction on chain, when the merchant names it. */ readonly transaction: string | undefined; } /** * The merchant's base64 `{ success, transaction, network, payer? }`, from the * header its version names, else the other one; `undefined` when it sent * neither. An unreadable header reads as `success: false`. */ export declare function merchantSettlementOf(headers: Headers, x402Version: 1 | 2): MerchantSettlement | undefined; /** `https://f/` and `https://f` are one facilitator. */ export declare function facilitatorBase(facilitator: string): string; /** The code a service put in an error body: `error`, `invalidReason`, `errorReason` or `code`. */ export declare function serviceCodeOf(body: unknown): string | undefined; /** * `POST url` with a JSON body, the response read whatever its status. A * transport failure propagates: the caller decides what an unanswered * request means, which differs by endpoint. */ export declare function postJson(fetchImpl: FetchLike, url: string, body: unknown): Promise; /** `POST /bridge/lookup`'s answer (§26.3). */ export interface BridgeLookup { readonly status: number; /** `authorized | paid | dead | refunded | disputed`, as the facilitator says. */ readonly state: string | undefined; } /** * `POST {facilitator}/bridge/lookup { contract_terms }` (§26.3): the * payment's state, asked with its preimage -- never by the public terms * hash, which would join a coin to its `payTo` for anyone (§26.12). `404` is * a payment this facilitator does not know. */ export declare function lookupBridgePayment(facilitator: string, terms: ContractTerms, fetchImpl: FetchLike): Promise;