All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
[0.3.3] - 2026-03-29
Fixed
- Payment signature format validation and SIWX ETS size cap (#39)
- Tightened Solana address validation and warn on missing idempotency cache (#36)
- Enforce
https://scheme on facilitatorbase_url— prevents plaintext credential leakage (#35) - Added 8KB payload size cap to
PaymentRequiredandPaymentResponseto prevent oversized payloads (#34) - TLS peer verification enabled by default and
PAYMENT-SIGNATUREheader size cap (#32)
Changed
- Bumped minimum Elixir to
~> 1.19(#33) - Optimized decimal parsing and centralized utility functions (#37)
Added
- Unit test for
HTTP.secure_pool_opts/0(#38)
[0.3.2] - 2026-03-01
Fixed
- Safe cache eviction with bounded cleanup to prevent full-table scans under load (#30)
- Atomic payment claim in PaymentGate plug to prevent double-settlement on concurrent requests (#30)
- SIWX ETSStorage read consistency — route
getthrough GenServer to prevent revoked session reads (#31) - Full-jitter exponential backoff in Facilitator.HTTP to prevent thundering herd on retries (#31)
- Base.decode64 padding safety in PaymentSignature and PaymentRequired (#31)
[0.3.1] - 2026-02-25
Fixed
- Fixed unbounded ETS cache growth vulnerability (DoS) — added
max_sizeconfig with LRU eviction (#17) - Fixed expired entries not being deleted during direct ETS reads (#25)
- Fixed
mix formatcompliance across all files
Added
- Comprehensive tests for
X402.Behaviour.implements?/2with doctests (#28) - Test coverage for facilitator hook exception and throw handling (#24)
- Optimized ETS cache with direct concurrent reads bypassing GenServer serialization (#25)
[0.3.0] - 2026-02-17
Added
- SIWX (Sign-In-With-X) — Repeat access without repayment (#14)
X402.Extensions.SIWX— CAIP-122 message construction and EIP-4361 (SIWE) formatX402.Extensions.SIWX.Verifier— behaviour for signature verificationX402.Extensions.SIWX.Verifier.Default— EVM signature verification viaex_secp256k1X402.Extensions.SIWX.Storage— behaviour for access record persistenceX402.Extensions.SIWX.ETSStorage— default ETS adapter with TTL and periodic cleanupSIGN-IN-WITH-Xheader encode/decode
- "upto" Scheme — Max-price bidding for flexible payments (#13)
PaymentRequiredencode/decode for"upto"scheme withmaxPricePaymentSignaturevalidation: payment value ≤ maxPrice- Facilitator client support for upto verification with hooks
PaymentGatePlug route config supports upto scheme
- Payment Identifier — Idempotency extension (#12)
X402.Extensions.PaymentIdentifier— encode/decode payment IDs in payloadsX402.Extensions.PaymentIdentifier.Cache— behaviour for deduplication cacheX402.Extensions.PaymentIdentifier.ETSCache— default ETS adapter with TTL
- Lifecycle Hooks — Behaviour-based hooks for verify/settle (#10)
before_verify/2,after_verify/2,before_settle/2,after_settle/2on_verify_failure/2,on_settle_failure/2- Context struct with request metadata, result, and error tracking
Changed
ex_secp256k1andex_keccakare now optional dependencies (only needed for SIWX)- ETS storage uses
:protectedaccess with direct reads bypassing GenServer for better concurrency
Fixed
- Credo strict compliance: implicit
try, redundantwithclauses - Dialyzer: unreachable pattern matches in PaymentIdentifier and SIWX Verifier
[0.1.0] - 2026-02-14
Added
X402.PaymentRequired— encode/decodePAYMENT-REQUIREDheaders (Base64 JSON)X402.PaymentSignature— decode/validatePAYMENT-SIGNATUREheadersX402.PaymentResponse— encodePAYMENT-RESPONSEsettlement headersX402.Facilitator— GenServer client for facilitator/verifyand/settleendpointsX402.Facilitator.HTTP— HTTP transport with retry logic and telemetryX402.Plug.PaymentGate— drop-in Plug middleware for payment gatingX402.Wallet— EVM and Solana wallet address validation- Comprehensive test suite with >90% coverage
- Full ExDoc documentation with guides