integraledger-terms 0.1.0__py3-none-any.whl

integraledger_terms/__init__.py

@@ -0,0 +1,261 @@
+"""The Python buyer gate: before a buyer signs, confirm that the advertised ATR hash is the SHA-256 of the bytes the
+seller's link serves, build the payment with that hash, and confirm the hash inside what was signed."""
+
+from ._agreement import agree
+from ._channels import ChannelHold, Within, open_channel, record_charge, within
+from ._core import MAX_ATR_BYTES, AtrHash, atr_hash, hash_equals
+from ._gate import check, confirm, finish, transact
+from ._types import (
+    Advertised,
+    Agreed,
+    AgreementReceipt,
+    Binding,
+    Checked,
+    Chosen,
+    Confirmed,
+    DeclineCode,
+    Declined,
+    Finished,
+    Inputs,
+    Json,
+    Next,
+    Refusal,
+    Signature,
+    Signer,
+    Step,
+    Transacted,
+    Unsigned,
+)
+from .bindings.mpp_card_stripe import charge_card, charge_stripe, subscription_stripe
+from .bindings.mpp_charge_evm import (
+    MppChargeEvmAuthorization,
+    MppChargeEvmHash,
+    MppChargeEvmPermit2,
+    MppChargeEvmTransaction,
+)
+from .bindings.mpp_charge_nearintents import MppChargeNearIntents
+from .bindings.mpp_charge_tempo import MppChargeTempoMemo, MppChargeTempoPush
+from .bindings.mpp_charge_usdc import MppChargeUsdcEvm, MppChargeUsdcGateway
+from .bindings.mpp_session import MppSessionEvm, MppSessionTempo, MppSubscriptionTempo
+from .bindings._channel import BatchUnsigned, ChannelRef
+from .bindings.ack_payment_request import AckPaymentRequest
+from .bindings.acp_checkout import AcpCheckoutDelegated, AcpCheckoutUndelegated
+from .bindings.ap2_checkout_mandate import Ap2CheckoutMandate
+from .bindings.card import CardMastercardViAutonomous, CardMastercardViImmediate, CardSellerReference, CardVisaTap
+from .bindings.lightning import (
+    MPP_CHARGE,
+    MppLightning,
+    MppLightningSession,
+    X402ExactLnbtc,
+    X402ExactLnbtcInvoiceNamed,
+)
+from .bindings.ucp import (
+    BOOKING_AP2_MANDATE,
+    BOOKING_UNSIGNED,
+    CHECKOUT_AP2_MANDATE,
+    CHECKOUT_UNSIGNED,
+    UcpAp2Mandate,
+    UcpUnsignedPairing,
+)
+from .bindings.x402_batch_settlement_cloudflare import X402BatchSettlementCloudflare
+from .bindings.x402_batch_settlement_eip155 import X402BatchSettlementEip155
+from .bindings.x402_evm import (
+    X402_AUTH_CAPTURE_EIP155_EIP3009,
+    X402_AUTH_CAPTURE_EIP155_PERMIT2,
+    X402_EXACT_EIP155_ERC7710,
+    X402_EXACT_EIP155_ERC7710_SALT,
+    X402_EXACT_EIP155_PERMIT2,
+    X402_UPTO_EIP155_PERMIT2,
+)
+from .bindings.x402_exact_eip155_eip3009 import X402ExactEip155Eip3009
+from .bindings.mpp_charge_solana import MPP_CHARGE_SOLANA, MPP_CHARGE_USDC_SOLANA
+from .bindings.mpp_session_solana import MPP_SESSION_SOLANA
+from .bindings.x402_batch_settlement_solana import X402BatchSettlementSolana
+from .bindings.x402_exact_solana import X402ExactSolana
+from .bindings.x402_upto_solana import X402UptoSolana
+from .bindings.mpp_charge_hedera import MppChargeHedera
+from .bindings.mpp_session_hedera import MppSessionHedera
+from .bindings.x402_exact_hedera import X402ExactHedera, X402ExactHederaExecutor
+from .bindings.x402_exact_near import X402ExactNear
+from .bindings.x402_exact_tron_lcp_trc20_memo import X402ExactTronLcpTrc20Memo
+from .bindings.x402_exact_tvm import X402ExactTvm
+from .bindings.x402_exact_starknet import X402ExactStarknet
+from .bindings.x402_exact_casper import X402ExactCasper
+from .bindings.x402_exact_aptos import X402ExactAptos
+from .bindings.x402_exact_polkadot_lcp_assets_remark import X402ExactPolkadotLcpAssetsRemark
+from .bindings.x402_exact_ccd import X402ExactCcd
+from .bindings.x402_exact_cardano import X402ExactCardano
+from .bindings.x402_exact_sui import X402ExactSui
+from .bindings.mpp_charge_stellar import MppChargeStellar
+from .bindings.mpp_charge_usdc_stacks import MppChargeUsdcStacks
+from .bindings.mpp_charge_xrpl import MppChargeXrpl
+from .bindings.mpp_session_xrpl import MppSessionXrpl
+from .bindings.x402_exact_algorand import X402ExactAlgorand
+from .bindings.x402_exact_stellar import X402ExactStellar
+from .bindings.x402_exact_xrpl import X402ExactXrpl
+
+X402_EXACT_EIP155_EIP3009: Binding = X402ExactEip155Eip3009()
+X402_EXACT_HEDERA: Binding = X402ExactHedera()
+MPP_CHARGE_HEDERA: Binding = MppChargeHedera()
+MPP_SESSION_HEDERA: Binding = MppSessionHedera()
+X402_EXACT_HEDERA_TRANSFER_EXECUTOR: Binding = X402ExactHederaExecutor()
+X402_EXACT_NEAR: Binding = X402ExactNear()
+X402_EXACT_TRON_LCP_TRC20_MEMO: Binding = X402ExactTronLcpTrc20Memo()
+X402_EXACT_TVM: Binding = X402ExactTvm()
+ACK_PAYMENT_REQUEST: Binding = AckPaymentRequest()
+ACP_CHECKOUT_DELEGATED: Binding = AcpCheckoutDelegated()
+ACP_CHECKOUT_UNDELEGATED: Binding = AcpCheckoutUndelegated()
+CARD_VISA_TAP: Binding = CardVisaTap()
+AP2_CHECKOUT_MANDATE: Binding = Ap2CheckoutMandate()
+UCP_CHECKOUT_AP2_MANDATE: Binding = UcpAp2Mandate(CHECKOUT_AP2_MANDATE)
+UCP_CHECKOUT_UNSIGNED: Binding = UcpUnsignedPairing(CHECKOUT_UNSIGNED)
+UCP_BOOKING_AP2_MANDATE: Binding = UcpAp2Mandate(BOOKING_AP2_MANDATE)
+UCP_BOOKING_UNSIGNED: Binding = UcpUnsignedPairing(BOOKING_UNSIGNED)
+X402_EXACT_LNBTC: Binding = X402ExactLnbtc()
+X402_EXACT_LNBTC_INVOICE_NAMED: Binding = X402ExactLnbtcInvoiceNamed()
+MPP_CHARGE_LIGHTNING: Binding = MppLightning(MPP_CHARGE)
+MPP_SESSION_LIGHTNING: Binding = MppLightningSession()
+CARD_MASTERCARD_VI_IMMEDIATE: Binding = CardMastercardViImmediate()
+CARD_MASTERCARD_VI_AUTONOMOUS: Binding = CardMastercardViAutonomous()
+CARD_SELLER_REFERENCE: Binding = CardSellerReference()
+X402_BATCH_SETTLEMENT_EIP155 = X402BatchSettlementEip155()
+X402_BATCH_SETTLEMENT_CLOUDFLARE = X402BatchSettlementCloudflare()
+X402_EXACT_SOLANA: Binding = X402ExactSolana()
+X402_BATCH_SETTLEMENT_SOLANA: Binding = X402BatchSettlementSolana()
+X402_UPTO_SOLANA: Binding = X402UptoSolana()
+
+MPP_CHARGE_EVM_AUTHORIZATION: Binding = MppChargeEvmAuthorization()
+MPP_CHARGE_EVM_PERMIT2: Binding = MppChargeEvmPermit2()
+MPP_CHARGE_EVM_TRANSACTION: Binding = MppChargeEvmTransaction()
+MPP_CHARGE_EVM_HASH: Binding = MppChargeEvmHash()
+MPP_CHARGE_CARD: Binding = charge_card()
+MPP_CHARGE_STRIPE: Binding = charge_stripe()
+MPP_SUBSCRIPTION_STRIPE: Binding = subscription_stripe()
+MPP_CHARGE_NEARINTENTS: Binding = MppChargeNearIntents()
+MPP_CHARGE_TEMPO_MEMO: Binding = MppChargeTempoMemo()
+MPP_CHARGE_TEMPO_PUSH: Binding = MppChargeTempoPush()
+MPP_CHARGE_USDC_EVM: Binding = MppChargeUsdcEvm()
+MPP_CHARGE_USDC_GATEWAY: Binding = MppChargeUsdcGateway()
+MPP_SESSION_EVM: Binding = MppSessionEvm()
+MPP_SESSION_TEMPO: Binding = MppSessionTempo()
+MPP_SUBSCRIPTION_TEMPO: Binding = MppSubscriptionTempo()
+X402_EXACT_STARKNET: Binding = X402ExactStarknet()
+X402_EXACT_CASPER: Binding = X402ExactCasper()
+X402_EXACT_APTOS: Binding = X402ExactAptos()
+X402_EXACT_POLKADOT_LCP_ASSETS_REMARK: Binding = X402ExactPolkadotLcpAssetsRemark()
+X402_EXACT_CCD: Binding = X402ExactCcd()
+X402_EXACT_CARDANO: Binding = X402ExactCardano()
+X402_EXACT_SUI: Binding = X402ExactSui()
+
+X402_EXACT_XRPL: Binding = X402ExactXrpl()
+X402_EXACT_ALGORAND: Binding = X402ExactAlgorand()
+X402_EXACT_STELLAR: Binding = X402ExactStellar()
+MPP_CHARGE_XRPL: Binding = MppChargeXrpl()
+MPP_CHARGE_STELLAR: Binding = MppChargeStellar()
+MPP_CHARGE_USDC_STACKS: Binding = MppChargeUsdcStacks()
+MPP_SESSION_XRPL: Binding = MppSessionXrpl()
+
+__all__ = [
+    "ACK_PAYMENT_REQUEST",
+    "ACP_CHECKOUT_DELEGATED",
+    "ACP_CHECKOUT_UNDELEGATED",
+    "AP2_CHECKOUT_MANDATE",
+    "CARD_MASTERCARD_VI_AUTONOMOUS",
+    "CARD_MASTERCARD_VI_IMMEDIATE",
+    "CARD_SELLER_REFERENCE",
+    "CARD_VISA_TAP",
+    "MAX_ATR_BYTES",
+    "MPP_CHARGE_CARD",
+    "MPP_CHARGE_EVM_AUTHORIZATION",
+    "MPP_CHARGE_EVM_HASH",
+    "MPP_CHARGE_EVM_PERMIT2",
+    "MPP_CHARGE_EVM_TRANSACTION",
+    "MPP_CHARGE_HEDERA",
+    "MPP_CHARGE_LIGHTNING",
+    "MPP_CHARGE_NEARINTENTS",
+    "MPP_CHARGE_SOLANA",
+    "MPP_CHARGE_STRIPE",
+    "MPP_CHARGE_TEMPO_MEMO",
+    "MPP_CHARGE_TEMPO_PUSH",
+    "MPP_CHARGE_USDC_EVM",
+    "MPP_CHARGE_USDC_GATEWAY",
+    "MPP_CHARGE_USDC_SOLANA",
+    "MPP_SESSION_EVM",
+    "MPP_SESSION_HEDERA",
+    "MPP_SESSION_LIGHTNING",
+    "MPP_SESSION_SOLANA",
+    "MPP_SESSION_TEMPO",
+    "MPP_SUBSCRIPTION_STRIPE",
+    "MPP_SUBSCRIPTION_TEMPO",
+    "UCP_BOOKING_AP2_MANDATE",
+    "UCP_BOOKING_UNSIGNED",
+    "UCP_CHECKOUT_AP2_MANDATE",
+    "UCP_CHECKOUT_UNSIGNED",
+    "X402_AUTH_CAPTURE_EIP155_EIP3009",
+    "X402_AUTH_CAPTURE_EIP155_PERMIT2",
+    "X402_BATCH_SETTLEMENT_CLOUDFLARE",
+    "X402_BATCH_SETTLEMENT_EIP155",
+    "X402_BATCH_SETTLEMENT_SOLANA",
+    "X402_EXACT_APTOS",
+    "X402_EXACT_CARDANO",
+    "X402_EXACT_CASPER",
+    "X402_EXACT_CCD",
+    "X402_EXACT_EIP155_EIP3009",
+    "X402_EXACT_EIP155_ERC7710",
+    "X402_EXACT_EIP155_ERC7710_SALT",
+    "X402_EXACT_EIP155_PERMIT2",
+    "X402_EXACT_HEDERA",
+    "X402_EXACT_HEDERA_TRANSFER_EXECUTOR",
+    "X402_EXACT_LNBTC",
+    "X402_EXACT_LNBTC_INVOICE_NAMED",
+    "X402_EXACT_NEAR",
+    "X402_EXACT_POLKADOT_LCP_ASSETS_REMARK",
+    "X402_EXACT_SOLANA",
+    "X402_EXACT_STARKNET",
+    "X402_EXACT_SUI",
+    "X402_EXACT_TRON_LCP_TRC20_MEMO",
+    "X402_EXACT_TVM",
+    "X402_UPTO_EIP155_PERMIT2",
+    "X402_UPTO_SOLANA",
+    "X402_EXACT_XRPL",
+    "X402_EXACT_ALGORAND",
+    "X402_EXACT_STELLAR",
+    "MPP_CHARGE_XRPL",
+    "MPP_CHARGE_STELLAR",
+    "MPP_CHARGE_USDC_STACKS",
+    "MPP_SESSION_XRPL",
+    "Advertised",
+    "Agreed",
+    "AgreementReceipt",
+    "AtrHash",
+    "BatchUnsigned",
+    "Binding",
+    "ChannelHold",
+    "ChannelRef",
+    "Checked",
+    "Chosen",
+    "Confirmed",
+    "DeclineCode",
+    "Declined",
+    "Finished",
+    "Inputs",
+    "Json",
+    "Next",
+    "Refusal",
+    "Signature",
+    "Signer",
+    "Step",
+    "Transacted",
+    "Unsigned",
+    "Within",
+    "agree",
+    "atr_hash",
+    "check",
+    "confirm",
+    "finish",
+    "hash_equals",
+    "open_channel",
+    "record_charge",
+    "transact",
+    "within",
+]

integraledger_terms/_agreement.py

@@ -0,0 +1,306 @@
+"""The agreement payment: ask the agreement URL for its challenge, pay it through the buyer piece of the pairing that
+placed it, a pairing whose payment is itself a public proof of the ATR hash, and return the resource's receipt once the
+payment is recorded. Nothing is signed when the challenge advertises another hash, and nothing is sent unless what was
+signed carries the hash. Once sent, the same signed payment is sent again after each 202, 5xx or timeout, each paid
+request bounded by min(maxTimeoutSeconds, 120) + 60 + 10 seconds and the whole exchange by the agreement option's
+maxTimeoutSeconds + 180 seconds; no second agreement payment is signed, and every decline after it was sent carries it
+as moved."""
+
+import asyncio
+import base64
+import binascii
+import json
+import re
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any
+
+import httpx
+
+from . import _gate
+from ._core import AtrHash, hash_equals, is_hash
+from .bindings._jose import UNPARSED, parse_json
+from .bindings._lcp import is_https_link, is_other_scheme_link
+from ._types import Advertised, AgreementReceipt, Agreed, Binding, Declined, Inputs, Moved, Refusal, Signer
+
+UNPAID_DEADLINE_S = 10.0
+EXCHANGE_CAP_S = 120
+SETTLE_S = 60
+VERIFY_S = 10
+WINDOW_EXTRA_S = 180
+MAX_ANSWER_BYTES = 65_536
+RETRY_DEFAULT_S = 2
+RETRY_MIN_S = 1
+
+_DECIMAL = re.compile(r"[0-9]{1,9}")
+
+
+def _clock() -> float:
+    return time.monotonic()
+
+
+async def _sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+@dataclass(frozen=True, slots=True)
+class _Answer:
+    status: int
+    payment_required: str | None
+    retry_after: str | None
+    body: bytes | None
+
+
+@dataclass(frozen=True, slots=True)
+class _Unanswered:
+    """A request that reached no answer: its deadline passed, or the URL could not be reached."""
+
+
+def _failed(detail: str, moved: Moved | None = None) -> Declined:
+    return Declined("agreement-failed", detail, moved)
+
+
+def _server_error(status: int) -> bool:
+    """A 5xx answer to the paid request, which is read as a timeout: the same payment is sent again."""
+    return 500 <= status <= 599
+
+
+def _to_base64(value: object) -> str:
+    """Standard base64 of the UTF-8 bytes of the compact JSON of value."""
+    text = json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+    return base64.b64encode(text.encode("utf-8")).decode("ascii")
+
+
+def _from_base64_json(header: str) -> object | None:
+    """The JSON value a base64 header carries, or None when it is not base64 of UTF-8 JSON."""
+    if len(header) > MAX_ANSWER_BYTES:
+        return None
+    try:
+        loaded: object = parse_json(base64.b64decode(header, validate=True).decode("utf-8"))
+    except (binascii.Error, UnicodeDecodeError, ValueError):
+        return None
+    return None if loaded is UNPARSED else loaded
+
+
+def _retry_seconds(header: str | None) -> int:
+    """retry-after in whole seconds, at least 1; 2 when absent or not a number of seconds."""
+    value = header.strip() if header is not None else None
+    if value is None or _DECIMAL.fullmatch(value) is None:
+        return RETRY_DEFAULT_S
+    return max(RETRY_MIN_S, int(value))
+
+
+async def _get(
+    fetch: httpx.AsyncClient, url: str, signature: str | None, seconds: float
+) -> _Answer | _Unanswered | Declined:
+    """One GET of the agreement URL, with no redirect and a deadline of seconds over headers and body. A 200 body is
+    read up to 64 KiB; any other body is left unread."""
+    headers = None if signature is None else {"PAYMENT-SIGNATURE": signature}
+    too_large = _failed("The agreement receipt is larger than 64 KiB.")
+    try:
+        async with asyncio.timeout(seconds):
+            async with fetch.stream("GET", url, headers=headers, follow_redirects=False) as response:
+                answer = _Answer(
+                    status=response.status_code,
+                    payment_required=response.headers.get("payment-required"),
+                    retry_after=response.headers.get("retry-after"),
+                    body=None,
+                )
+                if response.status_code != 200:
+                    return answer
+                declared = response.headers.get("content-length")
+                if declared is not None and declared.strip().isdigit() and int(declared) > MAX_ANSWER_BYTES:
+                    return too_large
+                body = bytearray()
+                async for chunk in response.aiter_bytes():
+                    body += chunk
+                    if len(body) > MAX_ANSWER_BYTES:
+                        return too_large
+                return replace(answer, body=bytes(body))
+    except Exception:
+        return _Unanswered()
+
+
+def _receipt(body: bytes | None, h: AtrHash) -> Agreed | Declined:
+    """The receipt a 200 carries, when it is the agreement receipt for h."""
+    try:
+        parsed: object = parse_json((body or b"").decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        return _failed("The agreement URL answered 200 without a JSON receipt.")
+    if parsed is UNPARSED or not isinstance(parsed, Mapping):
+        return _failed("The agreement URL answered 200 without a JSON receipt.")
+    atr_hash = parsed.get("atrHash")
+    if not isinstance(atr_hash, str) or not is_hash(atr_hash) or not hash_equals(atr_hash, h):
+        return _failed("The agreement receipt names another ATR hash.")
+    network = parsed.get("network")
+    transaction = parsed.get("transaction")
+    if parsed.get("agreed") is not True or not isinstance(network, str) or not isinstance(transaction, str):
+        return _failed("The agreement receipt is not a recorded agreement.")
+    return Agreed(AgreementReceipt(atr_hash=atr_hash, agreed=True, network=network, transaction=transaction))
+
+
+def _x402_bindings() -> tuple[Binding, ...]:
+    """The x402 pairings the gate serves, in the protocol package's order."""
+    from . import (
+        X402_AUTH_CAPTURE_EIP155_EIP3009,
+        X402_AUTH_CAPTURE_EIP155_PERMIT2,
+        X402_BATCH_SETTLEMENT_CLOUDFLARE,
+        X402_BATCH_SETTLEMENT_EIP155,
+        X402_BATCH_SETTLEMENT_SOLANA,
+        X402_EXACT_ALGORAND,
+        X402_EXACT_APTOS,
+        X402_EXACT_CARDANO,
+        X402_EXACT_CASPER,
+        X402_EXACT_CCD,
+        X402_EXACT_EIP155_EIP3009,
+        X402_EXACT_EIP155_ERC7710,
+        X402_EXACT_EIP155_ERC7710_SALT,
+        X402_EXACT_EIP155_PERMIT2,
+        X402_EXACT_HEDERA,
+        X402_EXACT_HEDERA_TRANSFER_EXECUTOR,
+        X402_EXACT_LNBTC,
+        X402_EXACT_LNBTC_INVOICE_NAMED,
+        X402_EXACT_NEAR,
+        X402_EXACT_POLKADOT_LCP_ASSETS_REMARK,
+        X402_EXACT_SOLANA,
+        X402_EXACT_STARKNET,
+        X402_EXACT_STELLAR,
+        X402_EXACT_SUI,
+        X402_EXACT_TRON_LCP_TRC20_MEMO,
+        X402_EXACT_TVM,
+        X402_EXACT_XRPL,
+        X402_UPTO_EIP155_PERMIT2,
+        X402_UPTO_SOLANA,
+    )
+
+    return (
+        X402_EXACT_EIP155_EIP3009,
+        X402_AUTH_CAPTURE_EIP155_EIP3009,
+        X402_AUTH_CAPTURE_EIP155_PERMIT2,
+        X402_BATCH_SETTLEMENT_CLOUDFLARE,
+        X402_BATCH_SETTLEMENT_EIP155,
+        X402_BATCH_SETTLEMENT_SOLANA,
+        X402_EXACT_ALGORAND,
+        X402_EXACT_APTOS,
+        X402_EXACT_CARDANO,
+        X402_EXACT_CASPER,
+        X402_EXACT_CCD,
+        X402_EXACT_EIP155_ERC7710,
+        X402_EXACT_EIP155_ERC7710_SALT,
+        X402_EXACT_EIP155_PERMIT2,
+        X402_EXACT_HEDERA,
+        X402_EXACT_HEDERA_TRANSFER_EXECUTOR,
+        X402_EXACT_LNBTC,
+        X402_EXACT_LNBTC_INVOICE_NAMED,
+        X402_EXACT_NEAR,
+        X402_EXACT_POLKADOT_LCP_ASSETS_REMARK,
+        X402_EXACT_SOLANA,
+        X402_EXACT_STARKNET,
+        X402_EXACT_STELLAR,
+        X402_EXACT_SUI,
+        X402_EXACT_TRON_LCP_TRC20_MEMO,
+        X402_EXACT_TVM,
+        X402_EXACT_XRPL,
+        X402_UPTO_EIP155_PERMIT2,
+        X402_UPTO_SOLANA,
+    )
+
+
+def _agreement_pairing(required: Mapping[str, Any]) -> tuple[Binding, Advertised, Mapping[str, Any]] | Declined:
+    """The pairing that placed the agreement option, when its payment is itself a public proof, with its read and the
+    option."""
+    accepts = required.get("accepts")
+    if not isinstance(accepts, Sequence) or isinstance(accepts, str) or not accepts or not isinstance(accepts[0], Mapping):
+        return Declined("offer-unreadable", "x402/no-payable-option")
+    for binding in _x402_bindings():
+        try:
+            read = binding.read(required)
+        except Exception:
+            continue
+        if isinstance(read, Advertised):
+            if getattr(binding, "public_proof", False) is not True:
+                return Declined("pairing-not-supported", f"The agreement pairing {binding.id} is not itself a public proof.")
+            return binding, read, accepts[0]
+    return Declined("pairing-not-supported", "The agreement option names no pairing the gate serves.")
+
+
+def _bounds(option: Mapping[str, Any]) -> tuple[int, int] | None:
+    """The paid request's deadline and the whole exchange's, in seconds, from the option's maxTimeoutSeconds."""
+    t = option.get("maxTimeoutSeconds")
+    if isinstance(t, bool) or not isinstance(t, int) or t <= 0 or t > 2**53 - 1:
+        return None
+    return min(t, EXCHANGE_CAP_S) + SETTLE_S + VERIFY_S, t + WINDOW_EXTRA_S
+
+
+async def agree(
+    h: AtrHash,
+    url: str,
+    signer: Signer,
+    fetch: httpx.AsyncClient,
+    *,
+    atr_bytes: bytes,
+    inputs: Inputs | None = None,
+    ns: str | None = None,
+) -> Agreed | Declined:
+    """Pay the agreement for h at url with signer, and return its receipt once recorded. atr_bytes are the ATR the
+    gate compared, for a pairing whose build reads them; inputs are the buyer's own chain values; ns is the namespace
+    of the pairing whose offer named the URL, which a refused URL's detail carries with the protocol package's code."""
+    if not is_https_link(url):
+        if ns is None:
+            return Declined("link-not-https", "The agreement URL is not an https URL.")
+        fault = "link-not-https" if is_other_scheme_link(url) else "legal-context-malformed"
+        return Declined("link-not-https", f"{ns}/{fault}")
+
+    unpaid = await _get(fetch, url, None, UNPAID_DEADLINE_S)
+    if isinstance(unpaid, Declined):
+        return unpaid
+    if isinstance(unpaid, _Unanswered):
+        return _failed("The agreement URL could not be reached.")
+    if unpaid.status == 200:
+        return _receipt(unpaid.body, h)
+    if unpaid.status == 202:
+        return Declined("agreement-pending", "An agreement payment for this ATR is already settling.")
+    if unpaid.status != 402:
+        return _failed(f"The agreement URL answered status {unpaid.status}.")
+
+    required = None if unpaid.payment_required is None else _from_base64_json(unpaid.payment_required)
+    if not isinstance(required, Mapping):
+        return _failed("The agreement URL answered 402 without a readable PAYMENT-REQUIRED.")
+    found = _agreement_pairing(required)
+    if isinstance(found, Declined):
+        return found
+    binding, read, option = found
+    limits = _bounds(option)
+    if limits is None:
+        return Declined("offer-unreadable", "x402/option-malformed")
+    if not hash_equals(read.h, h):
+        return Declined("hash-mismatch", "The agreement challenge advertises another ATR hash.")
+
+    paid = await _gate.pay(binding, read, required, signer, inputs if isinstance(inputs, Mapping) else {}, atr_bytes)
+    if isinstance(paid, Declined):
+        return paid
+    if paid is None:
+        return Declined("offer-unreadable", "The agreement payment gave nothing to sign.")
+    payment = _to_base64(paid.signed)
+    moved = Moved(paid.signed, atr_bytes, h)
+    pending = Declined("agreement-pending", "The agreement payment was sent and is not yet recorded.", moved)
+
+    request_s, exchange_s = limits
+    end = _clock() + exchange_s
+    while True:
+        remaining = end - _clock()
+        if remaining <= 0:
+            return pending
+        answer = await _get(fetch, url, payment, min(request_s, remaining))
+        if isinstance(answer, Declined):
+            return replace(answer, moved=moved)
+        wait = float(RETRY_DEFAULT_S)
+        if isinstance(answer, _Answer) and not _server_error(answer.status):
+            if answer.status == 200:
+                receipt = _receipt(answer.body, h)
+                return replace(receipt, moved=moved) if isinstance(receipt, Declined) else receipt
+            if answer.status != 202:
+                return _failed(f"The agreement URL answered status {answer.status} to the payment.", moved)
+            wait = float(_retry_seconds(answer.retry_after))
+        await _sleep(max(0.0, min(wait, end - _clock())))