x402-rack 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cd89fcca7ffc76bbe6c64b59f9a3874f31dcd4ef81b0b5e5de2bdf6ef06cb1a
-  data.tar.gz: 9ed4a30017bf928d1cfcce9da5ff119f7976fd2b30e83720ebed86e16d4ae5de
+  metadata.gz: d1c49c723394e852eb4f825b4f849967895cddc8a787dad72a5b6b3959ab618d
+  data.tar.gz: c417200fd8a715c7795d673f8e0f10b6627502aa6ee04e679265d44e3bb66e80
 SHA512:
-  metadata.gz: 6ef8a23f261ea47e375f0c40177713960f5023f624ffd52463f865143aa633503a8c4f048a5cb0d39dc5af5940de78faebd82d01de68161b7533b3571db44398
-  data.tar.gz: 917457986e6916d200acc8eee63a583984577ea6440dd5a6c8300c786f20288bf5228fde48e666e0b8bc56a42de8f6cdbcdda39ff387c60af715508725a92258
+  metadata.gz: 4b2a7277eea92f8f546fd45730ad860d239ec5df6592854942d214cc43415382f5f9adf33185cf871a81f971bd447e1dd804007597c9aa26a978d12cd6503728
+  data.tar.gz: 5143cd4fae5666792ab3338344ff7b28269b5544e353965d7c5e19be3395de2a68cbb07e8d1050840e0a97a58336694c89a6a0fbf6926066ae56b027b06b4f41

data/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-04-03
+
+### Added
+
+- **Server wallet** — `config.server_wif` builds a shared `ProtoWallet` (BRC-42/43 key derivation) for all gateways. Per-payment derived addresses, no address reuse. Falls back to static `payee_locking_script_hex` when not set. Per-gateway overrides (`wallet:`, `key_deriver:`) take precedence.
+- **Settlement worker** — `X402::SettlementWorker` for async background broadcast. Ruby stdlib only (Thread + Queue), exponential backoff retry, zero dependencies. Pluggable interface (`#enqueue(tx_binary)`) for Sidekiq/Redis.
+- **Per-route ARC thresholds** — `config.protect` accepts `arc_wait_for:` to override the gateway default. `:async` validates tx locally then enqueues, responding 200 immediately.
+- **Payment observer** — `X402::PaymentObserver` Rack middleware for voluntary ungated payments. Watches for payment headers, validates payee, enqueues to settlement worker. Never gates access. Configurable proof headers and `on_payment` callback.
+- **Pluggable recogniser** — `PaymentObserver` accepts `recogniser:` (any object responding to `#ours?(locking_script_hex)`) for BRC-29 derived address payment channels. `StaticRecogniser` wraps the existing static payee behaviour.
+- **Fiat-denominated pricing** — `config.protect` accepts `amount_usd:` resolved to sats at challenge time via `exchange_rate_provider`. Also accepts callable `amount_sats:` for any dynamic pricing. Provider interface: `#sats_for(currency, amount)`.
+
+### Changed
+
+- **`build_template` signature** — now accepts `required_sats` integer instead of route object. Gateways snapshot the resolved amount once per request.
+- **ProofGateway rejects callable pricing** — raises `ConfigurationError` at challenge time. The merkleworks canonical hash includes `amount_sats`; a callable would produce different hashes across requests.
+
+### Fixed
+
+- **`arc_wait_for` coerced to string** — prevents Symbol values being passed to ARC client.
+- **PaymentObserver pass-through guarantee** — enqueue/callback failures wrapped in rescue, never break the request.
+- **Recogniser interface validated** — `ConfigurationError` if recogniser doesn't respond to `#ours?`.
+- **Static payee hex canonicalised** — round-trips through `Script.from_hex.to_hex` in `StaticRecogniser`.
+- **Exchange rate provider validated** — `ConfigurationError` if provider doesn't respond to `#sats_for`.
+
 ## [0.3.0] - 2026-04-02
 
 ### Added
@@ -85,6 +109,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Operations docs** — deployment, performance, treasury/nonce lifecycle.
 - **Ecosystem docs** — Coinbase v2, merkleworks, BRC-105 positioning and header namespace reservations.
 
+[0.4.0]: https://github.com/sgbett/x402-rack/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/sgbett/x402-rack/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sgbett/x402-rack/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/sgbett/x402-rack/releases/tag/v0.1.0

data/README.md

@@ -6,9 +6,7 @@ The middleware is a pure dispatcher — it matches routes, issues payment challe
 
 ## Status
 
-Early development (v0.1.0). Architecture is defined; gateway implementation is in progress. See [DESIGN.md](DESIGN.md) for architecture notes.
-
-**This is pre-release software and should not be used for real-world monetary purposes.**
+v0.3.0 — PayGateway, ProofGateway, and BRC105Gateway all functional with e2e tests against BSV testnet. See [CHANGELOG.md](CHANGELOG.md) for release history and [DESIGN.md](DESIGN.md) for architecture notes.
 
 ## Installation
 
@@ -32,7 +30,7 @@ require "x402"
 
 X402.configure do |config|
   config.domain = "api.example.com"
-  config.payee_locking_script_hex = "76a914...88ac"
+  config.server_wif = ENV["SERVER_WIF"]  # recommended — derives unique addresses per payment
 
   # Shared ARC connection — built once, used by all gateways
   config.arc_url = "https://arc.taal.com"
@@ -40,8 +38,6 @@ X402.configure do |config|
 
   # Enable gateways — constructed automatically from shared deps
   config.enable :pay_gateway
-  config.enable :proof_gateway, nonce_provider: my_nonce_provider
-  config.enable :brc105_gateway, server_wif: "L3..."
 
   config.protect method: :GET, path: "/api/expensive", amount_sats: 100
 end
@@ -56,8 +52,8 @@ Each gateway type supports convenience options that expand into their full form:
 - **`:brc105_gateway`** — `server_wif: "L3..."` builds a `KeyDeriver` from a WIF
   string. `server_key:` accepts a `PrivateKey` directly. A default in-memory
   `PrefixStore` is used if `prefix_store:` is not provided.
-- **`:proof_gateway`** — `nonce_wif: "L3..."` builds a `PrivateKey` for the
-  `nonce_key:` parameter.
+- **`:proof_gateway`** — requires `nonce_provider:` callable. The provider
+  receives `(rack_request, payee:, amount:)` and returns nonce UTXO metadata.
 - **`:pay_gateway`** — pass-through options: `arc_wait_for:`, `arc_timeout:`,
   `binding_mode:`, `wallet:`, `challenge_secret:`.
 

data/lib/x402/bsv/brc105_gateway.rb

@@ -47,7 +47,7 @@ module X402
         end
 
         headers = {
-          "x-bsv-payment-satoshis-required" => route.amount_sats.to_s,
+          "x-bsv-payment-satoshis-required" => route.resolve_amount_sats.to_s,
           "x-bsv-payment-derivation-prefix" => prefix
         }
 
@@ -72,13 +72,14 @@ module X402
       # @param route [X402::Configuration::Route]
       # @return [SettlementResult]
       def settle!(_header_name, proof_payload, rack_request, route)
+        required_sats = route.resolve_amount_sats
         payment = parse_payment(proof_payload)
         prefix = payment["derivationPrefix"]
         suffix = payment["derivationSuffix"]
         validate_prefix_and_suffix!(prefix, suffix)
         subject_tx = parse_beef_transaction(payment["transaction"])
         expected_script = derive_payment_script(prefix, suffix, rack_request)
-        verify_payment_output!(subject_tx, route, expected_script)
+        verify_payment_output!(subject_tx, required_sats, expected_script)
         consume_prefix!(prefix)
         broadcast!(subject_tx)
         build_settlement_result(subject_tx)
@@ -139,13 +140,15 @@ module X402
         key if key.is_a?(String) && key.match?(COMPRESSED_PUBKEY_HEX)
       end
 
-      def verify_payment_output!(transaction, route, expected_script)
+      def verify_payment_output!(transaction, required_sats, expected_script)
         found = transaction.outputs.any? do |output|
-          output.locking_script == expected_script && output.satoshis >= route.amount_sats
+          output.locking_script == expected_script && output.satoshis >= required_sats
         end
         return if found
 
-        raise VerificationError.new("no output pays >= #{route.amount_sats} sats to derived address", status: 402)
+        raise VerificationError.new(
+          "no output pays >= #{required_sats} sats to derived address", status: 402
+        )
       end
 
       def broadcast!(transaction)

data/lib/x402/bsv/gateway.rb

@@ -44,14 +44,14 @@ module X402
       # @param rack_request [Rack::Request]
       # @param route [X402::Configuration::Route]
       # @return [Array(BSV::Transaction::Transaction, String)] transaction and payee script hex
-      def build_template(_rack_request, route)
+      def build_template(_rack_request, required_sats)
         tx = ::BSV::Transaction::Transaction.new
 
         # Output 0: payment (unique address if wallet configured, static otherwise)
         payee_hex = derive_payee_hex
         payee_script = ::BSV::Script::Script.from_hex(payee_hex)
         tx.add_output(::BSV::Transaction::TransactionOutput.new(
-                        satoshis: route.amount_sats,
+                        satoshis: required_sats,
                         locking_script: payee_script
                       ))
 

data/lib/x402/bsv/pay_gateway.rb

@@ -20,22 +20,25 @@ module X402
       ASSET = "BSV"
       SCHEME = "exact"
 
-      attr_reader :arc_client, :arc_wait_for, :arc_timeout, :binding_mode
+      attr_reader :arc_client, :arc_wait_for, :arc_timeout, :binding_mode, :settlement_worker
 
       # @param arc_client [#broadcast] ARC client for broadcasting
       # @param arc_wait_for [String] ARC X-WaitFor header value
       # @param arc_timeout [Integer] seconds before ARC timeout
       # @param binding_mode [Symbol] :strict or :permissive for OP_RETURN binding
       # @param payee_locking_script_hex [String, nil] payee script (falls back to config)
+      # @param settlement_worker [#enqueue, nil] async settlement worker
       def initialize(arc_client:, arc_wait_for: DEFAULT_ARC_WAIT_FOR,
                      arc_timeout: DEFAULT_ARC_TIMEOUT, binding_mode: :permissive,
-                     payee_locking_script_hex: nil, wallet: nil, challenge_secret: nil)
+                     payee_locking_script_hex: nil, wallet: nil, challenge_secret: nil,
+                     settlement_worker: nil)
         super(payee_locking_script_hex: payee_locking_script_hex, wallet: wallet,
               challenge_secret: challenge_secret)
         @arc_client = arc_client
         @arc_wait_for = arc_wait_for
         @arc_timeout = arc_timeout
         @binding_mode = binding_mode
+        @settlement_worker = settlement_worker
       end
 
       def challenge_headers(rack_request, route)
@@ -48,22 +51,24 @@ module X402
       end
 
       def settle!(_header_name, proof_payload, rack_request, route)
+        required_sats = route.resolve_amount_sats
         payload = decode_payment_payload(proof_payload)
-        verify_accepted!(payload, route)
+        verify_accepted!(payload, required_sats)
         accepted_payee = payload.dig("accepted", "payTo")
         pay_to_sig = payload.dig("accepted", "extra", "payToSig")
         verify_pay_to_signature!(accepted_payee, pay_to_sig)
         transaction = decode_transaction(payload)
-        verify_payment_output!(transaction, route, accepted_payee)
+        verify_payment_output!(transaction, required_sats, accepted_payee)
         verify_binding!(transaction, rack_request)
-        broadcast!(transaction)
+        settle_transaction!(transaction, route)
         build_settlement_result(transaction)
       end
 
       private
 
       def build_challenge(rack_request, route)
-        template, payee_hex = build_template(rack_request, route)
+        required_sats = route.resolve_amount_sats
+        template, payee_hex = build_template(rack_request, required_sats)
 
         # PayGateway includes OP_RETURN in the template (no fee delegation index issues)
         binding_hash = request_binding_hash(rack_request)
@@ -75,15 +80,15 @@ module X402
         {
           "x402Version" => 2,
           "resource" => { "url" => rack_request.path_info },
-          "accepts" => [build_accept_entry(payee_hex, route, template)]
+          "accepts" => [build_accept_entry(payee_hex, required_sats, template)]
         }
       end
 
-      def build_accept_entry(payee_hex, route, template)
+      def build_accept_entry(payee_hex, required_sats, template)
         {
           "scheme" => SCHEME,
           "network" => NETWORK,
-          "amount" => route.amount_sats.to_s,
+          "amount" => required_sats.to_s,
           "asset" => ASSET,
           "payTo" => payee_hex,
           "maxTimeoutSeconds" => DEFAULT_MAX_TIMEOUT_SECONDS,
@@ -101,7 +106,7 @@ module X402
         raise VerificationError.new("invalid payment payload", status: 400)
       end
 
-      def verify_accepted!(payload, route)
+      def verify_accepted!(payload, required_sats)
         accepted = payload["accepted"]
         raise VerificationError.new("missing accepted field", status: 400) unless accepted
         if accepted["network"] != NETWORK
@@ -109,9 +114,9 @@ module X402
         end
 
         amount = accepted["amount"].to_i
-        return unless amount < route.amount_sats
+        return unless amount < required_sats
 
-        raise VerificationError.new("insufficient amount: #{amount} < #{route.amount_sats}", status: 402)
+        raise VerificationError.new("insufficient amount: #{amount} < #{required_sats}", status: 402)
       end
 
       def decode_transaction(payload)
@@ -126,14 +131,14 @@ module X402
         raise VerificationError.new("failed to decode transaction", status: 400)
       end
 
-      def verify_payment_output!(transaction, route, payee_hex)
+      def verify_payment_output!(transaction, required_sats, payee_hex)
         payee_script = payee_script_from_hex(payee_hex)
         found = transaction.outputs.any? do |output|
-          output.locking_script == payee_script && output.satoshis >= route.amount_sats
+          output.locking_script == payee_script && output.satoshis >= required_sats
         end
         return if found
 
-        raise VerificationError.new("no output pays >= #{route.amount_sats} sats to payee", status: 402)
+        raise VerificationError.new("no output pays >= #{required_sats} sats to payee", status: 402)
       end
 
       def verify_binding!(transaction, rack_request)
@@ -148,8 +153,24 @@ module X402
         raise VerificationError.new("OP_RETURN request binding mismatch", status: 400)
       end
 
-      def broadcast!(transaction)
-        arc_client.broadcast(transaction, wait_for: arc_wait_for)
+      # Determine the effective wait_for strategy and either broadcast
+      # synchronously or enqueue for async settlement.
+      def settle_transaction!(transaction, route)
+        effective = (route.arc_wait_for || arc_wait_for).to_s
+
+        if effective == "async"
+          unless settlement_worker
+            raise ConfigurationError,
+                  "route arc_wait_for is :async but no settlement_worker configured"
+          end
+          settlement_worker.enqueue(transaction.to_binary)
+        else
+          broadcast!(transaction, wait_for: effective)
+        end
+      end
+
+      def broadcast!(transaction, wait_for: arc_wait_for)
+        arc_client.broadcast(transaction, wait_for: wait_for)
       rescue VerificationError
         raise
       rescue StandardError

data/lib/x402/bsv/proof_gateway.rb

@@ -36,6 +36,10 @@ module X402
       end
 
       def challenge_headers(rack_request, route)
+        if route.amount_sats.respond_to?(:call)
+          raise ConfigurationError,
+                "proof_gateway does not support callable amount_sats (fiat pricing) — use a static value"
+        end
         challenge = build_merkleworks_challenge(rack_request, route)
         { "X402-Challenge" => challenge.to_header }
       end
@@ -45,10 +49,11 @@ module X402
       end
 
       def settle!(_header_name, proof_payload, rack_request, route)
+        required_sats = route.resolve_amount_sats
         proof = Proof.from_header(proof_payload)
         challenge = reconstruct_challenge(rack_request)
         run_protocol_checks!(challenge, proof, rack_request)
-        decode_and_verify_transaction!(proof, challenge, route)
+        decode_and_verify_transaction!(proof, challenge, required_sats)
         check_mempool!(proof.txid)
 
         SettlementResult.new(txid: proof.txid, network: "bsv:mainnet")
@@ -58,9 +63,10 @@ module X402
 
       def build_merkleworks_challenge(rack_request, route)
         config = X402.configuration
+        required_sats = route.resolve_amount_sats
         payee_hex = derive_payee_hex
 
-        nonce = @nonce_provider.call(rack_request, payee: payee_hex, amount: route.amount_sats)
+        nonce = @nonce_provider.call(rack_request, payee: payee_hex, amount: required_sats)
 
         # Profile B: provider returns a pre-signed partial_tx (binary)
         template_binary = nonce[:partial_tx]
@@ -74,7 +80,7 @@ module X402
           query: rack_request.query_string,
           req_headers_sha256: RequestBinding.headers_sha256(rack_request),
           req_body_sha256: RequestBinding.body_sha256(rack_request),
-          amount_sats: route.amount_sats,
+          amount_sats: required_sats,
           payee_locking_script_hex: payee_hex,
           nonce_txid: nonce[:txid],
           nonce_vout: nonce[:vout],
@@ -114,13 +120,13 @@ module X402
         Verification::ProtocolChecks.check_expiry!(challenge)
       end
 
-      def decode_and_verify_transaction!(proof, challenge, route)
+      def decode_and_verify_transaction!(proof, challenge, required_sats)
         transaction = decode_transaction(proof)
         check_txid!(transaction, proof)
         check_nonce_input!(transaction, challenge)
         verify_nonce_provenance!(transaction, challenge) if challenge.partial_tx_b64
         server_payee_hex = resolve_static_payee_hex
-        verify_payment_output!(transaction, route, server_payee_hex)
+        verify_payment_output!(transaction, required_sats, server_payee_hex)
         transaction
       end
 
@@ -169,14 +175,14 @@ module X402
         raise VerificationError, "nonce provenance check failed"
       end
 
-      def verify_payment_output!(transaction, route, payee_hex)
+      def verify_payment_output!(transaction, required_sats, payee_hex)
         payee_script = payee_script_from_hex(payee_hex)
         found = transaction.outputs.any? do |output|
-          output.locking_script == payee_script && output.satoshis >= route.amount_sats
+          output.locking_script == payee_script && output.satoshis >= required_sats
         end
         return if found
 
-        raise VerificationError.new("no output pays >= #{route.amount_sats} sats to payee", status: 402)
+        raise VerificationError.new("no output pays >= #{required_sats} sats to payee", status: 402)
       end
 
       def check_mempool!(txid)

data/lib/x402/configuration.rb

@@ -2,13 +2,22 @@
 
 module X402
   class Configuration
-    Route = Struct.new(:http_method, :path, :amount_sats, keyword_init: true)
+    # Route holds a raw +amount_sats+ that may be an Integer or a callable.
+    # The +resolve_amount_sats+ method evaluates callables at access time,
+    # enabling fiat-denominated pricing with live exchange rates.
+    Route = Struct.new(:http_method, :path, :amount_sats, :arc_wait_for, keyword_init: true) do
+      # Resolves +amount_sats+ — if it's a callable (Proc/Lambda),
+      # it is evaluated each time to get the current sats amount.
+      def resolve_amount_sats
+        amount_sats.respond_to?(:call) ? amount_sats.call : amount_sats
+      end
+    end
 
     GATEWAY_METHODS = %i[challenge_headers proof_header_names settle!].freeze
 
     PAY_GATEWAY_KNOWN_OPTS = %i[
       arc_client payee_locking_script_hex arc_wait_for arc_timeout
-      binding_mode wallet challenge_secret
+      binding_mode wallet challenge_secret settlement_worker
     ].freeze
 
     PROOF_GATEWAY_KNOWN_OPTS = %i[
@@ -27,7 +36,8 @@ module X402
     }.freeze
 
     attr_accessor :domain, :payee_locking_script_hex, :gateways,
-                  :arc_url, :arc_api_key, :arc_client
+                  :arc_url, :arc_api_key, :arc_client, :server_wif,
+                  :exchange_rate_provider
     attr_reader :routes, :gateway_specs
 
     def initialize
@@ -60,13 +70,38 @@ module X402
       @shared_arc_client ||= build_arc_client
     end
 
+    # Returns a memoised ProtoWallet built from +server_wif+.
+    # Used as the shared wallet for all gateways, providing per-payment
+    # derived addresses via BRC-42/43 key derivation.
+    #
+    # @return [BSV::Wallet::ProtoWallet, nil]
+    def shared_wallet
+      return if @server_wif.nil? || @server_wif.empty?
+
+      @shared_wallet ||= build_wallet
+    end
+
     # Register a protected route.
     #
     # @param method [String] HTTP method or "*" for any
     # @param path [String, Regexp] exact path or pattern
-    # @param amount_sats [Integer] required payment in satoshis
-    def protect(method:, path:, amount_sats:)
-      @routes << Route.new(http_method: method.upcase, path: path, amount_sats: amount_sats)
+    # @param amount_sats [Integer, #call] required payment in satoshis.
+    #   Accepts a static Integer or a callable (Proc/Lambda) that returns
+    #   the current sats amount at challenge time. Use a callable for
+    #   fiat-denominated pricing with live exchange rates.
+    # @param amount_usd [Numeric, nil] convenience — price in USD, resolved
+    #   to sats at challenge time via +exchange_rate_provider+. Mutually
+    #   exclusive with +amount_sats+.
+    # @param arc_wait_for [String, Symbol, nil] per-route ARC settlement override.
+    #   +nil+ (default) uses the gateway's +arc_wait_for+ setting.
+    #   A string value (e.g. +"SEEN_ON_NETWORK"+, +"MINED"+) overrides the
+    #   gateway default for synchronous broadcast.
+    #   +:async+ validates the transaction locally then enqueues it for
+    #   background settlement via the gateway's +settlement_worker+, returning
+    #   200 immediately without waiting for ARC confirmation.
+    def protect(method:, path:, amount_sats: nil, amount_usd: nil, arc_wait_for: nil)
+      sats = resolve_amount(amount_sats, amount_usd)
+      @routes << Route.new(http_method: method.upcase, path: path, amount_sats: sats, arc_wait_for: arc_wait_for)
     end
 
     # Find the matching route for a request method and path.
@@ -82,10 +117,7 @@ module X402
     def validate!
       raise ConfigurationError, "domain is required" if domain.nil? || domain.empty?
 
-      if payee_locking_script_hex.nil? || payee_locking_script_hex.empty?
-        raise ConfigurationError,
-              "payee_locking_script_hex is required"
-      end
+      validate_payee_source!
       build_gateways_from_specs! if gateways.empty? && !gateway_specs.empty?
       validate_gateways!
       raise ConfigurationError, "at least one route must be protected" if routes.empty?
@@ -121,12 +153,44 @@ module X402
       end
     end
 
+    def resolve_amount(amount_sats, amount_usd)
+      raise ConfigurationError, "amount_sats and amount_usd are mutually exclusive" if amount_sats && amount_usd
+
+      return amount_sats if amount_sats
+
+      raise ConfigurationError, "protect requires amount_sats: or amount_usd:" unless amount_usd
+      unless exchange_rate_provider
+        raise ConfigurationError, "amount_usd requires exchange_rate_provider to be configured"
+      end
+      unless exchange_rate_provider.respond_to?(:sats_for)
+        raise ConfigurationError, "exchange_rate_provider must respond to #sats_for(currency, amount)"
+      end
+
+      provider = exchange_rate_provider
+      usd = amount_usd
+      -> { provider.sats_for("USD", usd) }
+    end
+
+    def validate_payee_source!
+      has_payee = payee_locking_script_hex && !payee_locking_script_hex.empty?
+      has_wallet = @server_wif && !@server_wif.empty?
+
+      return if has_payee || has_wallet
+
+      raise ConfigurationError, "server_wif or payee_locking_script_hex is required"
+    end
+
     def build_arc_client
       raise ConfigurationError, "arc_url is required (or inject arc_client directly)" if arc_url.nil? || arc_url.empty?
 
       ::BSV::Network::ARC.new(arc_url, api_key: arc_api_key)
     end
 
+    def build_wallet
+      key = ::BSV::Primitives::PrivateKey.from_wif(@server_wif)
+      ::BSV::Wallet::ProtoWallet.new(key)
+    end
+
     def build_gateways_from_specs!
       require_relative "bsv"
       require "bsv-wallet"
@@ -143,9 +207,11 @@ module X402
 
     def build_pay_gateway(klass, options)
       reject_unknown_options!(:pay_gateway, options, PAY_GATEWAY_KNOWN_OPTS)
-      opts = { arc_client: options[:arc_client] || shared_arc_client,
-               payee_locking_script_hex: options[:payee_locking_script_hex] || payee_locking_script_hex }
-      %i[arc_wait_for arc_timeout binding_mode wallet challenge_secret].each do |key|
+      wallet = options[:wallet] || shared_wallet
+      opts = { arc_client: options[:arc_client] || shared_arc_client }
+      opts[:payee_locking_script_hex] = options[:payee_locking_script_hex] || payee_locking_script_hex
+      opts[:wallet] = wallet if wallet
+      %i[arc_wait_for arc_timeout binding_mode challenge_secret settlement_worker].each do |key|
         opts[key] = options[key] if options.key?(key)
       end
       klass.new(**opts)
@@ -174,19 +240,22 @@ module X402
         raise ConfigurationError,
               "brc105_gateway: #{key_sources.join(", ")} are mutually exclusive — provide only one"
       end
-      if key_sources.empty?
-        raise ConfigurationError,
-              "brc105_gateway requires one of: key_deriver:, server_wif:, or server_key:"
-      end
 
       key_deriver = if options.key?(:key_deriver)
                       options[:key_deriver]
                     elsif options.key?(:server_wif)
                       ::BSV::Wallet::KeyDeriver.new(::BSV::Primitives::PrivateKey.from_wif(options[:server_wif]))
-                    else
+                    elsif options.key?(:server_key)
                       ::BSV::Wallet::KeyDeriver.new(options[:server_key])
+                    elsif shared_wallet
+                      shared_wallet.key_deriver
                     end
 
+      unless key_deriver
+        raise ConfigurationError,
+              "brc105_gateway requires one of: key_deriver:, server_wif:, server_key:, or top-level server_wif"
+      end
+
       klass.new(
         key_deriver: key_deriver,
         prefix_store: options[:prefix_store] || X402::BSV::PrefixStore::Memory.new,

data/lib/x402/payment_observer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "bsv-sdk"
+
+module X402
+  # Rack middleware that silently observes voluntary payment headers and
+  # enqueues them for settlement. Never gates access — requests always
+  # pass through regardless of payment presence or validity.
+  #
+  # Only enqueues transactions that contain at least one recognised output
+  # — the observer is not an open relay.
+  #
+  # == Static payee (simple)
+  #
+  #   use X402::PaymentObserver,
+  #     worker: settlement_worker,
+  #     payee_locking_script_hex: "76a914...88ac"
+  #
+  # == Recogniser (derived addresses / payment channels)
+  #
+  #   use X402::PaymentObserver,
+  #     worker: settlement_worker,
+  #     recogniser: session_tracker   # responds to #ours?(locking_script_hex)
+  #
+  # The recogniser is duck-typed — any object responding to
+  # +#ours?(locking_script_hex)+ qualifies. For payment channels with
+  # BRC-29 derived addresses, the recogniser tracks which derived addresses
+  # belong to active sessions.
+  #
+  # Any object responding to +#enqueue(tx_binary)+ satisfies the worker
+  # interface (e.g. +X402::SettlementWorker+, a Sidekiq job, etc.).
+  class PaymentObserver
+    DEFAULT_PROOF_HEADERS = %w[Payment-Signature].freeze
+
+    # @param app [#call] next Rack app in the stack
+    # @param worker [#enqueue] settlement worker for background broadcast
+    # @param payee_locking_script_hex [String, nil] static payee script hex
+    # @param recogniser [#ours?, nil] object that recognises derived payment addresses.
+    #   Takes precedence over +payee_locking_script_hex+ when both are provided.
+    # @param proof_headers [Array<String>] HTTP header names to watch for payments
+    # @param on_payment [#call, nil] optional callback invoked with the raw tx
+    #   binary after successful enqueue, for application-level tracking
+    def initialize(app, worker:, payee_locking_script_hex: nil, recogniser: nil,
+                   proof_headers: DEFAULT_PROOF_HEADERS, on_payment: nil)
+      @app = app
+      @worker = worker
+      @recogniser = build_recogniser(recogniser, payee_locking_script_hex)
+      @proof_headers = proof_headers
+      @on_payment = on_payment
+    end
+
+    def call(env)
+      observe_payment(env)
+      @app.call(env)
+    end
+
+    private
+
+    def build_recogniser(recogniser, payee_hex)
+      if recogniser
+        unless recogniser.respond_to?(:ours?)
+          raise ConfigurationError,
+                "PaymentObserver recogniser must respond to #ours?(locking_script_hex)"
+        end
+        return recogniser
+      end
+
+      unless payee_hex
+        raise ConfigurationError,
+              "PaymentObserver requires recogniser: or payee_locking_script_hex:"
+      end
+
+      StaticRecogniser.new(payee_hex)
+    end
+
+    def observe_payment(env)
+      @proof_headers.each do |header_name|
+        rack_key = "HTTP_#{header_name.upcase.tr("-", "_")}"
+        value = env[rack_key]
+        next if value.nil? || value.empty?
+
+        tx_binary = extract_and_validate(value)
+        next unless tx_binary
+
+        enqueue_payment(tx_binary)
+        break
+      end
+    end
+
+    def enqueue_payment(tx_binary)
+      @worker.enqueue(tx_binary)
+      @on_payment&.call(tx_binary)
+    rescue StandardError
+      # Never let enqueue/callback failures break the request pass-through
+    end
+
+    def extract_and_validate(proof_payload)
+      json = Base64.strict_decode64(proof_payload)
+      payload = JSON.parse(json)
+      rawtx_hex = payload.dig("payload", "rawtx")
+      return unless rawtx_hex
+
+      tx_binary = [rawtx_hex].pack("H*")
+      tx = ::BSV::Transaction::Transaction.from_binary(tx_binary)
+      return unless recognised?(tx)
+
+      tx_binary
+    rescue StandardError
+      nil
+    end
+
+    def recognised?(transaction)
+      transaction.outputs.any? do |output|
+        @recogniser.ours?(output.locking_script.to_hex)
+      end
+    end
+
+    # Built-in recogniser for a single static payee address.
+    # Used when +payee_locking_script_hex+ is provided without a custom recogniser.
+    class StaticRecogniser
+      def initialize(payee_locking_script_hex)
+        @payee_hex = ::BSV::Script::Script.from_hex(payee_locking_script_hex).to_hex
+      end
+
+      def ours?(locking_script_hex)
+        locking_script_hex == @payee_hex
+      end
+    end
+  end
+end

data/lib/x402/settlement_worker.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module X402
+  # Background thread that broadcasts transactions to ARC with exponential
+  # backoff retry. Uses Ruby stdlib Thread + Queue (zero dependencies).
+  #
+  # Any object responding to +#enqueue(tx_binary)+ satisfies the pluggable
+  # worker interface expected by PayGateway's async settlement path.
+  class SettlementWorker
+    ACCEPTABLE_STATUSES = %w[SEEN_ON_NETWORK ANNOUNCED_TO_NETWORK MINED].freeze
+
+    attr_reader :max_retries
+
+    def initialize(arc_client:, max_retries: 5)
+      @arc_client = arc_client
+      @max_retries = max_retries
+      @queue = Queue.new
+      @thread = nil
+      @mutex = Mutex.new
+    end
+
+    def enqueue(tx_binary)
+      ensure_thread_running
+      @queue.push(tx_binary)
+    end
+
+    def stop
+      thread_to_join = nil
+      @mutex.synchronize do
+        return unless @thread&.alive?
+
+        @queue.push(:shutdown)
+        thread_to_join = @thread
+        @thread = nil
+      end
+      thread_to_join&.join
+    end
+
+    private
+
+    def ensure_thread_running
+      @mutex.synchronize do
+        @thread = nil unless @thread&.alive?
+        @thread ||= Thread.new { process_loop }
+      end
+    end
+
+    def process_loop
+      loop do
+        item = @queue.pop
+        break if item == :shutdown
+
+        broadcast_with_retry(item)
+      end
+    end
+
+    def broadcast_with_retry(tx_binary, attempt = 0)
+      result = @arc_client.broadcast(tx_binary, wait_for: "SEEN_ON_NETWORK")
+      return if ACCEPTABLE_STATUSES.include?(result.tx_status)
+      return if attempt >= @max_retries
+
+      sleep(2**attempt)
+      broadcast_with_retry(tx_binary, attempt + 1)
+    rescue StandardError
+      return if attempt >= @max_retries
+
+      sleep(2**attempt)
+      broadcast_with_retry(tx_binary, attempt + 1)
+    end
+  end
+end

data/lib/x402/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module X402
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/x402.rb

@@ -5,6 +5,8 @@ require_relative "x402/errors"
 require_relative "x402/settlement_result"
 require_relative "x402/configuration"
 require_relative "x402/middleware"
+require_relative "x402/payment_observer"
+require_relative "x402/settlement_worker"
 
 module X402
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: x402-rack
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -120,11 +120,13 @@ files:
 - lib/x402/configuration.rb
 - lib/x402/errors.rb
 - lib/x402/middleware.rb
+- lib/x402/payment_observer.rb
 - lib/x402/protocol/base64url.rb
 - lib/x402/protocol/challenge.rb
 - lib/x402/protocol/proof.rb
 - lib/x402/protocol/request_binding.rb
 - lib/x402/settlement_result.rb
+- lib/x402/settlement_worker.rb
 - lib/x402/verification/protocol_checks.rb
 - lib/x402/version.rb
 - sig/x402.rbs