@spec extract_payload(envelope()) :: {:ok, payload()} | {:error, verify_error()}

Extracts the payload from a signed envelope without verifying it.

For "eip712" the transmitted payload is returned; for "jws" the JWS payload segment is decoded. Use verify_offer/2 / verify_receipt/2 for verified reads.

Examples

iex> X402.Extensions.OfferReceipt.extract_payload(%{
...>   "format" => "eip712",
...>   "payload" => %{"version" => 1},
...>   "signature" => "0xsig"
...> })
{:ok, %{"version" => 1}}

iex> X402.Extensions.OfferReceipt.extract_payload(%{"format" => "carrier-pigeon"})
{:error, {:unsupported_format, "carrier-pigeon"}}

@spec offer_digest(payload()) ::
  {:ok, <<_::256>>} | {:error, payload_error() | :missing_dependency}

Computes the EIP-712 digest of an offer payload (§4.3).

Returns keccak256(0x19 0x01 || domainSeparator || structHash) where the domain is {name: "x402 offer", version: "1", chainId: 1}. An absent validUntil is hashed as 0. Requires the optional ex_keccak dependency.

@spec offer_payload(keyword()) ::
  {:ok, payload()} | {:error, {:unknown_network, String.t()}}

Builds an offer payload (§4.2) in wire shape.

The :network is normalized to CAIP-2 with to_caip2/1, as the specification requires for offer payloads. version is always the current payload schema version (1).

Options

• :resource_url (String.t/0) - Required. The paid resource URL.

• :scheme (String.t/0) - Required. Payment scheme identifier (e.g. "exact").

• :network (String.t/0) - Required. Network identifier — CAIP-2 or an x402 v1 name (converted via to_caip2/1).

• :asset (String.t/0) - Required. Token contract address or "native".

• :pay_to (String.t/0) - Required. Recipient wallet address.

• :amount - Required. Required payment amount in atomic units (encoded as a string).

• :valid_until (non_neg_integer/0) - Unix timestamp (seconds) when the offer expires. Omit for no expiry.

Examples

iex> X402.Extensions.OfferReceipt.offer_payload(
...>   resource_url: "https://api.example.com/premium-data",
...>   scheme: "exact",
...>   network: "base",
...>   asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
...>   pay_to: "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
...>   amount: 10_000,
...>   valid_until: 1_703_123_516
...> )
{:ok,
 %{
   "version" => 1,
   "resourceUrl" => "https://api.example.com/premium-data",
   "scheme" => "exact",
   "network" => "eip155:8453",
   "asset" => "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
   "payTo" => "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
   "amount" => "10000",
   "validUntil" => 1703123516
 }}

iex> X402.Extensions.OfferReceipt.offer_payload(
...>   resource_url: "https://a.example",
...>   scheme: "exact",
...>   network: "unknown-net",
...>   asset: "native",
...>   pay_to: "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
...>   amount: "1"
...> )
{:error, {:unknown_network, "unknown-net"}}

@spec sign_offer(payload(), X402.Signer.t(), keyword()) ::
  {:ok, envelope()} | {:error, verify_error() | term()}

Signs an offer payload as an EIP-712 artifact through an X402.Signer.

Computes the EIP-712 digest with the fixed offer domain (name: "x402 offer", version: "1", chainId: 1, §3.2) and the canonical Offer type (§4.3), signs it through signer, and returns the transmitted envelope

%{"format" => "eip712", "payload" => payload, "signature" => "0x..."}

Per §4.3, an absent validUntil is signed and transmitted as 0. Requires the optional ex_keccak dependency ({:error, :missing_dependency} without it).

Options

• :accept_index (non_neg_integer/0) - Index into accepts[] this offer corresponds to. An unsigned convenience field (§4.1.1) — clients match offers by payload fields.

@spec sign_offer_jws(
  payload(),
  keyword()
) ::
  {:ok, envelope()}
  | {:error, X402.Extensions.OfferReceipt.JWS.sign_error() | payload_error()}

Signs an offer payload as a compact JWS artifact.

The payload travels inside the JWS, so the envelope omits payload (§3.1.1). Optional payload fields stay omitted (no zero-filling — that rule is EIP-712 specific).

key_opts are the X402.Extensions.OfferReceipt.JWS.sign/2 options (:alg, :kid, :key) plus the :accept_index envelope option.

Examples

{:ok, offer} =
  X402.Extensions.OfferReceipt.sign_offer_jws(payload,
    alg: "EdDSA",
    kid: "did:web:api.example.com#key-1",
    key: ed25519_seed,
    accept_index: 0
  )

@spec verify_offer(
  envelope(),
  keyword()
) :: {:ok, verification()} | {:error, verify_error()}

Verifies a signed offer envelope (§4.5).

For "eip712" artifacts, recomputes the EIP-712 digest from the payload exactly as transmitted and recovers the signer address (requires the optional ex_secp256k1 / ex_keccak dependencies). For "jws" artifacts, verifies the compact JWS against the :public_key option.

Returns {:ok, %{format: ..., payload: ...}} with :signer (EIP-712, the recovered address) or :header (JWS, the protected header with alg and kid).

Options

• :expected_signer (String.t/0) - EIP-712 only: EVM address the recovered signer must equal (case-insensitive), e.g. the offer's payTo. When the recovered signer differs, verification fails with {:error, :unauthorized_signer}.

• :public_key (String.t/0) - JWS only (required for "jws" artifacts): raw public key bytes — a 32-byte Ed25519 key for EdDSA, a SEC1 secp256k1 point for ES256K.

• :algs - JWS only: accepted algorithms. The default value is ["ES256K", "EdDSA"].