@callback amount(challenge :: challenge()) :: Decimal.t()

Extract the payment amount from a parsed challenge.

Returns the amount in human-decimal units (e.g. 1.00 means $1.00 USDC, not 1_000_000 atomic units). Implementations are expected to normalize via Raxol.Payments.Assets.to_human/2 using the challenge's asset metadata. The SpendingPolicy caps are written in the same units.

@callback build_payment(challenge :: challenge(), wallet :: module()) ::
  {:ok, headers()} | {:error, term()}

Build authorization headers for the payment.

Signs the challenge using the provided wallet module and returns headers to attach to the retry request.

@callback detect?(status :: integer(), headers :: headers()) :: boolean()

Check if this protocol can handle the given 402 response.

Inspects the response status and headers to determine if this protocol's payment flow applies.

@callback name() :: String.t()

Human-readable protocol name.

@callback parse_challenge(headers :: headers()) :: {:ok, challenge()} | {:error, term()}

Parse the 402 response headers into a challenge map.

Extracts payment requirements (price, currency, recipient, network) from the protocol-specific headers.

@callback parse_receipt(headers :: headers()) :: {:ok, receipt()} | {:error, term()}

Parse the payment receipt from a successful response.

Extracts confirmation details (tx hash, amount settled, etc.) from the response headers after a successful paid request.