@spec bound_salt(String.t() | nil, String.t() | nil, String.t()) ::
  {:ok, String.t()} | {:error, encode_error()}

Computes the bound salt: keccak256(abi.encode(SALT_BINDING_TYPEHASH, receiverAuthorizer, policy, saltNonce)).

Absent addresses are the zero address; salt_nonce is 32-byte hex.

@spec bytes32_hex(term()) :: {:ok, String.t()} | {:error, :invalid_bytes32}

Spells a uint256 (integer or decimal string) as the zero-padded 32-byte hex the scheme pins for salt and saltNonce.

Examples

iex> X402.AuthCapture.EVM.bytes32_hex(255)
{:ok, "0x00000000000000000000000000000000000000000000000000000000000000ff"}

iex> X402.AuthCapture.EVM.bytes32_hex("0x" <> String.duplicate("ab", 32))
{:ok, "0x" <> String.duplicate("ab", 32)}

iex> X402.AuthCapture.EVM.bytes32_hex("nope")
{:error, :invalid_bytes32}

@spec encode_payment_info(map()) ::
  {:ok, binary()} | {:error, {:invalid_payment_info, String.t()}}

ABI-encodes a PaymentInfo struct into its twelve 32-byte words.

Validates each field against its Solidity width (uint120, uint48, uint16) and returns {:error, {:invalid_payment_info, field}} for the first field that does not fit.

Examples

iex> info = %{
...>   "operator" => "0x1563915e194d8cfba1943570603f7606a3115508",
...>   "payer" => "0x19e7e376e7c213b7e7e7e46cc70a5dd086daff2a",
...>   "receiver" => "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
...>   "token" => "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
...>   "maxAmount" => "10000",
...>   "preApprovalExpiry" => 1,
...>   "authorizationExpiry" => 2,
...>   "refundExpiry" => 3,
...>   "minFeeBps" => 0,
...>   "maxFeeBps" => 100,
...>   "feeReceiver" => "0x0000000000000000000000000000000000000000",
...>   "salt" => "0x" <> String.duplicate("00", 31) <> "01"
...> }
iex> {:ok, encoded} = X402.AuthCapture.EVM.encode_payment_info(info)
iex> byte_size(encoded)
384

iex> X402.AuthCapture.EVM.encode_payment_info(%{"operator" => "0x1"})
{:error, {:invalid_payment_info, "operator"}}

@spec match_payment_info(map(), map()) :: :ok | {:error, term()}

Checks stored PaymentInfo against its original requirements.

Reconstructs and compares the canonical ABI encoding, including every Solidity width, and checks expiry ordering. The payer, preapproval expiry and salt must come from retained client state; this does not verify their signature, salt commitment, or onchain existence.

Examples

iex> X402.AuthCapture.EVM.match_payment_info(%{}, %{})
{:error, {:missing_field, "captureAuthorizer"}}

@spec parse_uint256(term()) :: {:ok, non_neg_integer()} | {:error, :invalid_amount}

Parses a non-negative uint256 integer or decimal string.

Rejects signs, whitespace and strings longer than 78 digits before integer conversion. Hex input is reserved for the bytes32 helpers.

Examples

iex> X402.AuthCapture.EVM.parse_uint256("1000")
{:ok, 1000}

iex> X402.AuthCapture.EVM.parse_uint256("+1")
{:error, :invalid_amount}

@spec payment_info(map(), String.t(), non_neg_integer(), String.t()) ::
  {:ok, payment_info()} | {:error, {:missing_field, String.t()}}

Builds the PaymentInfo struct for a payment from its requirements.

payer is the client address, pre_approval_expiry the authorization's validBefore / deadline, and salt the wire payload.salt. Every other field comes from requirements and its extra, as the spec's PaymentInfo appendix sets out.

Examples

iex> requirements = %{
...>   "amount" => "10000",
...>   "asset" => "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
...>   "payTo" => "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
...>   "extra" => %{
...>     "captureAuthorizer" => "0x1563915e194d8cfba1943570603f7606a3115508",
...>     "feeRecipient" => "0x0000000000000000000000000000000000000000",
...>     "captureDeadline" => 1_800_000_000,
...>     "refundDeadline" => 1_800_100_000,
...>     "minFeeBps" => 0,
...>     "maxFeeBps" => 0
...>   }
...> }
iex> {:ok, info} =
...>   X402.AuthCapture.EVM.payment_info(
...>     requirements,
...>     "0x19e7e376e7c213b7e7e7e46cc70a5dd086daff2a",
...>     1_799_000_000,
...>     "0x" <> String.duplicate("ab", 32)
...>   )
iex> {info["operator"], info["maxAmount"], info["authorizationExpiry"]}
{"0x1563915e194d8cfba1943570603f7606a3115508", "10000", 1800000000}

iex> X402.AuthCapture.EVM.payment_info(%{"extra" => %{}}, "0x19e7e376e7c213b7e7e7e46cc70a5dd086daff2a", 1, "0x00")
{:error, {:missing_field, "captureAuthorizer"}}

@spec payment_info_from_payload(map(), map()) ::
  {:ok, payment_info()}
  | {:error, :payload_format | {:missing_field, String.t()}}

Reconstructs the PaymentInfo a client payment payload commits to.

Accepts the full v2 envelope or the inner payload map. The payer and preApprovalExpiry come from the EIP-3009 authorization (from, validBefore) or the permit2Authorization (from, deadline), and the salt from payload.salt.

@spec payment_info_hash(non_neg_integer(), String.t(), map()) ::
  {:ok, String.t()} | {:error, encode_error()}

Computes AuthCaptureEscrow.getHash(paymentInfo) — the escrow's canonical payment identifier, as 0x-prefixed hex.

keccak256(abi.encode(chainId, escrow, keccak256(abi.encode(PAYMENT_INFO_TYPEHASH, info)))).

@spec payment_info_type() :: String.t()

The PaymentInfo EIP-712 type string, whose keccak256 is the escrow's PAYMENT_INFO_TYPEHASH.

@spec permit2_nonce(String.t()) :: {:ok, String.t()} | {:error, :invalid_bytes32}

Spells a 32-byte hex value as the decimal uint256 string Permit2 nonces use on the wire.

Examples

iex> X402.AuthCapture.EVM.permit2_nonce("0x" <> String.duplicate("00", 31) <> "ff")
{:ok, "255"}

iex> X402.AuthCapture.EVM.permit2_nonce("0xzz")
{:error, :invalid_bytes32}

@spec random_bytes32() :: String.t()

Returns fresh random 32 bytes as zero-padded 0x hex — a salt when unbound, a saltNonce when bound.

Examples

iex> X402.AuthCapture.EVM.random_bytes32() =~ ~r/^0x[0-9a-f]{64}$/
true

@spec salt_binding_type() :: String.t()

The salt-binding type string (SALT_BINDING_TYPEHASH preimage).

@spec signature_nonce(non_neg_integer(), String.t(), map()) ::
  {:ok, String.t()} | {:error, encode_error()}

Computes the payment's signatureNonce: the payer-agnostic identity that becomes the EIP-3009 nonce (as 0x hex) and the Permit2 nonce (as the decimal uint256, see permit2_nonce/1).

The struct is hashed with payer zeroed and every other field holding its onchain value.