x402-rack 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c88a0b6770421ac5fa4d83a410a9951f9544af70325fe467bc29676b7d0957f
-  data.tar.gz: b0f8f30ff3a63b6a83794a148e4e8e8aed60555e337c70a6925539147b2a4850
+  metadata.gz: 5cd89fcca7ffc76bbe6c64b59f9a3874f31dcd4ef81b0b5e5de2bdf6ef06cb1a
+  data.tar.gz: 9ed4a30017bf928d1cfcce9da5ff119f7976fd2b30e83720ebed86e16d4ae5de
 SHA512:
-  metadata.gz: 8208b0343e9f84a4d7f998a42d574627f92c6457f40a4d8732aa3ed6ff7383789410fc895a43118db49e45bde9a31fb79283524e3b7c4677dcff1465d92119cd
-  data.tar.gz: d65d2ed290d6c097a3a0bccfda18f2634c458e59dace5b4a86ae478616525483adbeb5ba7b62d112f2bfd4475c0a0668772aa1baf2c92e16c52f547bda6f591e
+  metadata.gz: 6ef8a23f261ea47e375f0c40177713960f5023f624ffd52463f865143aa633503a8c4f048a5cb0d39dc5af5940de78faebd82d01de68161b7533b3571db44398
+  data.tar.gz: 917457986e6916d200acc8eee63a583984577ea6440dd5a6c8300c786f20288bf5228fde48e666e0b8bc56a42de8f6cdbcdda39ff387c60af715508725a92258

data/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+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.3.0] - 2026-04-02
+
+### Added
+
+- **Configuration DSL** — `config.enable :pay_gateway` with shared dependencies (ARC client, payee script) wired automatically. Convenience options: `server_wif:` builds KeyDeriver, `nonce_wif:` builds PrivateKey, default PrefixStore for BRC-105. Per-gateway overrides supported. Deferred construction at `validate!` time. Full backwards compatibility with `config.gateways = [...]`.
+- **Copilot review instructions** — `.github/copilot-instructions.md` with payment-bypass-focused review guidance.
+- **Dependabot** — weekly checks for bundler and GitHub Actions dependencies.
+
+### Changed
+
+- **Treasury refactor** — ProofGateway no longer holds the treasury's private key (`nonce_key:` removed). The `nonce_provider` callable now optionally returns a pre-signed `partial_tx:` for Profile B. Signing responsibility pushed from gateway to treasury. Trust boundary: `[(X)+(B)] <-> [(T)]`.
+- **nonce_provider interface** — now receives `payee:` and `amount:` kwargs. Profile detection moved from constructor config to provider response.
+- **Dependencies** — `bsv-sdk ~> 0.4`, `bsv-wallet ~> 0.2` (BRC-100 wallet interface now available).
+
+### Fixed
+
+- **ARC wait_for enforced** — PayGateway now passes `arc_wait_for` to `broadcast(tx, wait_for:)`. Previously stored but never used.
+- **Mempool status validated** — ProofGateway `check_mempool!` now verifies `tx_status` is `SEEN_ON_NETWORK`, `ANNOUNCED_TO_NETWORK`, or `MINED`. Non-propagated statuses (`RECEIVED`, `STORED`) correctly rejected.
+- **Error messages hardened** — all gateways, middleware, and protocol parsers now return fixed generic strings. No SDK exception messages forwarded to HTTP clients.
+- **Config DSL memoisation** — `shared_arc_client` checks injected `arc_client` on every call, not just first.
+
+### Removed
+
+- **`nonce_key:` parameter** from ProofGateway constructor (breaking change for Profile B users — signing moves to nonce_provider).
+- **`nonce_wif:` and `nonce_key:` convenience options** from configuration DSL (no longer applicable).
+
+## [0.2.0] - 2026-03-30
+
+### Added
+
+- **BRC-105 Gateway** — `X402::BSV::BRC105Gateway` implementing the BSV Association's native payment protocol (`x-bsv-*` headers). Uses BRC-29 key derivation for unique per-payment addresses and AtomicBEEF (BRC-95) transaction format.
+- **Prefix Store** — `X402::BSV::PrefixStore::Memory` for BRC-105 derivation prefix replay protection. Thread-safe via Monitor, with TTL-based expiry (default 300s) and max capacity cap (default 10,000).
+- **BRC-103 composition** — BRC105Gateway works standalone (advertises server identity key in header) or composes with future BRC-103 mutual authentication middleware. Detects mode automatically from `env['brc103.identity_key']`.
+- **BRC-105 e2e test** — full standalone payment flow against BSV testnet (derive address, build tx, encode AtomicBEEF, verify, broadcast).
+- **Comprehensive documentation** — scheme doc (`docs/schemes/brc-105.md`), process flow diagrams for both standalone and authenticated modes, security analysis, client integration guide.
+
+### Security
+
+- Derivation prefix consumed after full transaction validation, not before (prevents MITM prefix burning).
+- BRC-103 identity key validated as compressed pubkey hex before trusting as BRC-29 counterparty (prevents sentinel injection).
+- SDK exception messages not forwarded to HTTP clients — fixed generic strings returned.
+- `PrefixStore::Memory` bounded with TTL and max capacity to prevent heap exhaustion from unauthenticated challenge requests.
+- `StoreFullError` returns 503 (server at capacity), not 400.
+
+## [0.1.0] - 2026-03-28
+
+### Added
+
+#### Middleware
+
+- **`X402::Middleware`** — pure Rack dispatcher for payment-gated HTTP. No blockchain knowledge, no keys. Matches routes, polls gateways for challenge headers, dispatches proofs to the matching gateway.
+- **Multi-gateway support** — multiple gateways can be configured simultaneously. The middleware issues challenge headers from all gateways and dispatches proofs to whichever gateway recognises the proof header.
+- **Payment content negotiation** — different x402 ecosystems use different HTTP headers. A server sends multiple challenge headers; the client picks the one it can satisfy.
+
+#### Gateways
+
+- **`X402::BSV::PayGateway`** — Coinbase v2 headers (`Payment-Required` / `Payment-Signature` / `Payment-Response`). Server broadcasts via ARC. HMAC-signed `payToSig` prevents payee address tampering. OP_RETURN request binding (strict/permissive mode). This is the recommended "BSV way" — vendor verifies, vendor broadcasts, vendor serves.
+- **`X402::BSV::ProofGateway`** — merkleworks x402 headers (`X402-Challenge` / `X402-Proof`). Client broadcasts, server checks mempool. Profile A (bare nonce metadata) and Profile B (pre-signed template with 0xC3 nonce signature for provenance).
+- **`X402::BSV::Gateway`** — base class for template-based gateways. Builds partial transaction templates with payment output and OP_RETURN binding. Supports wallet-based address derivation (BRC-43) or static payee address.
+
+#### Configuration
+
+- **Route protection** — `config.protect method: :GET, path: "/api/expensive", amount_sats: 100`
+- **Duplicate proof header detection** — validates no two gateways claim the same proof header name.
+
+#### Testing
+
+- **E2e test suite** — PayGateway, ProofGateway (Profile B), and fee delegation flows tested against BSV testnet with real ARC broadcasts.
+- **E2ELogger** — pretty logging with actors, timestamps, transaction links, and timestamped markdown log files.
+- **Fee delegation e2e** — treasury + client + delegator + payee four-wallet flow with 0xC3 sighash alignment.
+
+#### Documentation
+
+- **Architecture docs** — middleware as dispatcher, gateway interface, component boundaries, unified template model, 0xC3 sighash rationale.
+- **Scheme docs** — BSV-pay and BSV-proof with headers, challenge/settlement flows, replay protection.
+- **Process flow diagrams** — mermaid sequence diagrams for PayGateway and ProofGateway.
+- **Security docs** — threat model, payToSig HMAC, nonce provenance (Profile B), OP_RETURN binding, error handling.
+- **Operations docs** — deployment, performance, treasury/nonce lifecycle.
+- **Ecosystem docs** — Coinbase v2, merkleworks, BRC-105 positioning and header namespace reservations.
+
+[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

@@ -20,20 +20,77 @@ gem "x402-rack", git: "https://github.com/sgbett/x402-rack.git"
 
 ## Usage
 
+### Configuration DSL (recommended)
+
+The DSL handles shared dependencies (ARC client, payee script) and gateway
+construction automatically. You declare *what* you want; the middleware builds it
+at validation time.
+
 ```ruby
 # config.ru or Rails initialiser
 require "x402"
 
+X402.configure do |config|
+  config.domain = "api.example.com"
+  config.payee_locking_script_hex = "76a914...88ac"
+
+  # Shared ARC connection — built once, used by all gateways
+  config.arc_url = "https://arc.taal.com"
+  config.arc_api_key = "..."          # optional — ARC supports anonymous access
+
+  # 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
+
+use X402::Middleware
+```
+
+#### Convenience options
+
+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.
+- **`:pay_gateway`** — pass-through options: `arc_wait_for:`, `arc_timeout:`,
+  `binding_mode:`, `wallet:`, `challenge_secret:`.
+
+#### Per-gateway overrides
+
+Any gateway can override shared dependencies:
+
+```ruby
+config.enable :pay_gateway, arc_client: my_custom_arc
+config.enable :proof_gateway, nonce_provider: np, payee_locking_script_hex: "deadbeef..."
+```
+
+#### Order independence
+
+`enable` records gateway specs; construction is deferred to `validate!`. This
+means `arc_url` can be set after `enable` calls — order within the configure
+block does not matter.
+
+### Manual gateway construction (power-user escape hatch)
+
+For full control, construct gateways yourself and assign them directly. This
+bypasses DSL construction entirely and works exactly as before:
+
+```ruby
 X402.configure do |config|
   config.domain = "api.example.com"
   config.payee_locking_script_hex = "76a914...88ac"
 
   config.gateways = [
     X402::BSV::PayGateway.new(
-      arc_url: "https://arc.taal.com",
-      arc_api_key: "..."
+      arc_client: BSV::Network::ARC.new("https://arc.taal.com", api_key: "..."),
+      payee_locking_script_hex: "76a914...88ac"
     ),
-    # BRC-105 gateway (BSV Association payment protocol)
     X402::BSV::BRC105Gateway.new(
       key_deriver: BSV::Wallet::KeyDeriver.new(server_private_key),
       prefix_store: X402::BSV::PrefixStore::Memory.new,
@@ -47,6 +104,9 @@ end
 use X402::Middleware
 ```
 
+If `config.gateways` is set to a non-empty array, any `enable` calls are
+ignored.
+
 ## How It Works
 
 1. Client requests a protected resource

data/docs/architecture.md

@@ -15,7 +15,7 @@ The middleware never decodes transactions, checks mempool, broadcasts, or intera
 
 ## Gateways
 
-Gateways are pluggable backends that handle chain-specific settlement. They **can** hold keys and sign transactions — they are separate components from the gatekeeper. Each gateway:
+Gateways are pluggable backends that handle chain-specific settlement. They delegate key management and signing to external providers (e.g. the treasury via `nonce_provider`). Each gateway:
 
 - Builds challenge data (including partial transaction templates)
 - Verifies and settles proofs

data/docs/operations/deployment.md

@@ -69,8 +69,7 @@ config.gateways = [
   X402::BSV::PayGateway.new(arc_client: arc),
   X402::BSV::ProofGateway.new(
     nonce_provider: treasury,
-    arc_client: arc,
-    nonce_key: nonce_key
+    arc_client: arc
   )
 ]
 ```

data/docs/operations/treasury.md

@@ -12,7 +12,7 @@ The treasury creates 1-sat P2PKH outputs locked to the nonce key. Each output be
 
 When the ProofGateway builds a challenge, it requests a nonce from the treasury (via the `nonce_provider` callable). The nonce UTXO details (txid, vout, satoshis, locking_script_hex) are included in the challenge.
 
-In Profile B, the gateway signs the nonce input with `0xC3` and includes the pre-signed template in the challenge.
+In Profile B, the treasury signs the nonce input with `0xC3` and returns the pre-signed template (as `partial_tx` binary) to the gateway. The gateway appends the OP_RETURN and includes the template in the challenge.
 
 ### Spending
 
@@ -51,12 +51,20 @@ The treasury is not on the critical path for settlement — it only participates
 
 ## Current Implementation
 
-The `nonce_provider` is currently a raw callable injected into ProofGateway:
+The `nonce_provider` is a callable injected into ProofGateway. It receives `payee:` and `amount:` kwargs so the treasury can build the template:
 
 ```ruby
-nonce_provider = ->(request) {
+# Profile A — bare UTXO metadata
+nonce_provider = ->(request, payee:, amount:) {
   { txid: "...", vout: 0, satoshis: 1, locking_script_hex: "76a914...88ac" }
 }
+
+# Profile B — treasury builds and signs the template
+nonce_provider = ->(request, payee:, amount:) {
+  tx = build_and_sign_template(payee: payee, amount: amount)
+  { txid: "...", vout: 0, satoshis: 1, locking_script_hex: "76a914...88ac",
+    partial_tx: tx.to_binary }
+}
 ```
 
 Full wallet-backed treasury integration (basket-managed nonce pool, automatic minting, timelock expiry) is tracked in [bsv-ruby-sdk#196](https://github.com/sgbett/bsv-ruby-sdk/issues/196).

data/docs/process-flow/proof-gateway.md

@@ -81,7 +81,7 @@ sequenceDiagram
 ## Notes
 
 - **Client broadcasts, not server** — broadcasting is settlement, not authorisation. Keeps the server stateless (per Rui at merkleworks).
-- **Profile B template** — the challenge includes a pre-signed template (`partial_tx_b64`) with the nonce input at index 0 signed with `0xC3`. The client extends it by appending funding inputs.
+- **Profile B template** — the treasury (via `nonce_provider`) builds and signs the template. The gateway appends the OP_RETURN and includes it in the challenge as `partial_tx_b64`. The nonce input at index 0 is signed with `0xC3`. The client extends it by appending funding inputs.
 - **0xC3 sighash** — `SIGHASH_SINGLE | ANYONECANPAY | FORKID` commits to output 0 (payment) while allowing additional inputs and outputs. See [architecture.md](../architecture.md#why-0xc3-for-the-nonce-signature).
 - **Fee delegation is optional** — shown as `opt` in the diagram. Most clients can fund their own fees (1-50 sats). The delegator adds fee inputs and signs only those.
 - **Client signs with 0xC1** — `SIGHASH_ALL | ANYONECANPAY | FORKID` on funding inputs. Commits to all outputs but allows the delegator to append fee inputs.

data/docs/schemes/bsv-proof.md

@@ -11,21 +11,23 @@ Client broadcasts, server checks mempool. Proof-of-payment model. Nonce-bound wi
 
 ## Profiles
 
-### Profile A (no nonce key)
+### Profile A (no partial template)
 
 The challenge includes nonce UTXO metadata only. The client must construct the entire transaction including the nonce input. No cryptographic proof of nonce provenance.
 
 Suitable for deployments using an external treasury service that returns bare UTXO references.
 
-### Profile B (with nonce key) — recommended
+### Profile B (treasury-signed template) — recommended
 
-The gateway holds a nonce key and produces a **pre-signed template**:
+The **treasury** (via the `nonce_provider` callable) builds and signs a partial template. The gateway receives it and appends the OP_RETURN request binding:
 
 - Input 0: nonce UTXO, signed with `SIGHASH_SINGLE | ANYONECANPAY | FORKID` (`0xC3`)
-- Output 0: payment (committed by the signature)
-- Output 1: OP_RETURN binding (appendable)
+- Output 0: payment (committed by the treasury's signature)
+- Output 1: OP_RETURN binding (appended by the gateway after receiving the template)
 
-The client extends the template by adding funding inputs. The `0xC3` signature proves the server issued the nonce — this is the provenance guarantee.
+The gateway never holds a private key. Profile B is detected from the presence of `partial_tx` in the provider response.
+
+The client extends the template by adding funding inputs. The `0xC3` signature proves the treasury issued the nonce — this is the provenance guarantee.
 
 The template is included in the challenge as `partial_tx_b64` (base64-encoded), excluded from the canonical challenge hash (merkleworks spec compliance).
 
@@ -79,7 +81,29 @@ Per Rui at merkleworks: broadcasting is settlement, not authorisation. If the se
 
 See [operations/treasury.md](../operations/treasury.md) for nonce lifecycle.
 
+## Nonce Provider Interface
+
+The `nonce_provider` is a callable that receives `(rack_request, payee:, amount:)` and returns a hash:
+
+```ruby
+# Profile A — bare UTXO metadata
+provider = ->(request, payee:, amount:) {
+  { txid: "...", vout: 0, satoshis: 1, locking_script_hex: "76a914...88ac" }
+}
+
+# Profile B — includes pre-signed partial template
+provider = ->(request, payee:, amount:) {
+  tx = build_and_sign_template(payee: payee, amount: amount)
+  { txid: "...", vout: 0, satoshis: 1, locking_script_hex: "76a914...88ac",
+    partial_tx: tx.to_binary }
+}
+```
+
+The presence of `:partial_tx` in the response triggers Profile B behaviour. The gateway appends the OP_RETURN after deserialising the template.
+
 ## Infrastructure Required
 
-- **Treasury**: mints nonce UTXOs, holds the nonce key, signs templates (Profile B)
+Trust boundary: `[(X)+(B)] <-> [(T)]` — the server (x402-rack + BSV gateway) never holds keys; the treasury is a separate trust domain.
+
+- **Treasury** (`nonce_provider`): mints nonce UTXOs, holds keys, signs templates (Profile B)
 - **ARC**: mempool queries (`status(txid)`)

data/docs/security.md

@@ -48,7 +48,7 @@ The `0xC3` signature on input 0 proves the server issued the nonce. At settlemen
 
 ### Nonce Key Validation
 
-At challenge time (template signing), the gateway validates that the nonce key's public key hash matches the nonce UTXO's P2PKH locking script. Catches misconfiguration before producing an invalid template.
+Key validation is the treasury's responsibility. The gateway never holds a private key — the `nonce_provider` callable builds and signs the template. Misconfiguration (key/UTXO mismatch) is caught at settlement time when `verify_input(0)` fails.
 
 ### Payee Verification
 

data/lib/x402/bsv/pay_gateway.rb

@@ -97,8 +97,8 @@ module X402
       def decode_payment_payload(proof_payload)
         json = Base64.strict_decode64(proof_payload)
         JSON.parse(json)
-      rescue ArgumentError, JSON::ParserError => e
-        raise VerificationError.new("invalid payment payload: #{e.message}", status: 400)
+      rescue ArgumentError, JSON::ParserError
+        raise VerificationError.new("invalid payment payload", status: 400)
       end
 
       def verify_accepted!(payload, route)
@@ -122,8 +122,8 @@ module X402
         ::BSV::Transaction::Transaction.from_binary(raw)
       rescue VerificationError
         raise
-      rescue StandardError => e
-        raise VerificationError.new("failed to decode transaction: #{e.message}", status: 400)
+      rescue StandardError
+        raise VerificationError.new("failed to decode transaction", status: 400)
       end
 
       def verify_payment_output!(transaction, route, payee_hex)
@@ -149,9 +149,11 @@ module X402
       end
 
       def broadcast!(transaction)
-        arc_client.broadcast(transaction)
-      rescue StandardError => e
-        raise VerificationError.new("ARC broadcast failed: #{e.message}", status: 502)
+        arc_client.broadcast(transaction, wait_for: arc_wait_for)
+      rescue VerificationError
+        raise
+      rescue StandardError
+        raise VerificationError.new("ARC broadcast failed", status: 502)
       end
 
       def build_settlement_result(transaction)

data/lib/x402/bsv/proof_gateway.rb

@@ -17,23 +17,22 @@ module X402
     # Proof:     X402-Proof (echoed challenge hash + rawtx + txid)
     #
     # Supports two modes:
-    # - Profile A (no nonce_key): challenge includes nonce UTXO metadata only
-    # - Profile B (with nonce_key): challenge includes pre-signed template with
-    #   nonce input at index 0 signed with 0xC3
+    # - Profile A: challenge includes nonce UTXO metadata only
+    # - Profile B: nonce_provider returns a pre-signed partial_tx template
     class ProofGateway < Gateway
-      NONCE_SIGHASH = ::BSV::Transaction::Sighash::SINGLE_FORK_ID_ANYONE_CAN_PAY
+      ACCEPTABLE_MEMPOOL_STATUSES = %w[SEEN_ON_NETWORK ANNOUNCED_TO_NETWORK MINED].freeze
 
-      # @param nonce_provider [#call] callable returning nonce UTXO hash
+      # @param nonce_provider [#call] callable returning nonce UTXO hash;
+      #   receives (rack_request, payee:, amount:) kwargs.
+      #   Profile B providers include :partial_tx (binary) in the response.
       # @param arc_client [#status] ARC client for mempool queries
-      # @param nonce_key [BSV::Primitives::PrivateKey, nil] key for signing nonce input (Profile B)
       # @param payee_locking_script_hex [String, nil] payee script (falls back to config)
-      def initialize(nonce_provider:, arc_client:, nonce_key: nil,
+      def initialize(nonce_provider:, arc_client:,
                      payee_locking_script_hex: nil, wallet: nil, challenge_secret: nil)
         super(payee_locking_script_hex: payee_locking_script_hex, wallet: wallet,
               challenge_secret: challenge_secret)
         @nonce_provider = nonce_provider
         @arc_client = arc_client
-        @nonce_key = nonce_key
       end
 
       def challenge_headers(rack_request, route)
@@ -57,57 +56,14 @@ module X402
 
       private
 
-      # Build a Profile B template: nonce input (signed 0xC3) + payment + OP_RETURN.
-      # The 0xC3 signature commits to output 0 (payment) only.
-      # The OP_RETURN is added AFTER signing — it's unsigned data.
-      # Delegated clients should pop the OP_RETURN before adding their change
-      # (to preserve SIGHASH_SINGLE index alignment) and re-append it last.
-      # Falls back to base class (Profile A) when nonce_key is nil.
-      def build_proof_template(rack_request, route, nonce)
-        return super(rack_request, route) unless @nonce_key
-
-        validate_nonce_key!(nonce)
-
-        tx = ::BSV::Transaction::Transaction.new
-
-        # Input 0: nonce UTXO (will be signed with 0xC3)
-        nonce_script = ::BSV::Script::Script.from_hex(nonce[:locking_script_hex])
-        nonce_input = ::BSV::Transaction::TransactionInput.new(
-          prev_tx_id: [nonce[:txid]].pack("H*").reverse,
-          prev_tx_out_index: nonce[:vout]
-        )
-        nonce_input.source_satoshis = nonce[:satoshis]
-        nonce_input.source_locking_script = nonce_script
-        tx.add_input(nonce_input)
-
-        # Output 0: payment (committed by 0xC3 signature on input 0)
-        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,
-                        locking_script: payee_script
-                      ))
-
-        # Sign input 0 with 0xC3 (commits to output 0 only)
-        tx.sign(0, @nonce_key, NONCE_SIGHASH)
-
-        # Output 1: OP_RETURN binding (added AFTER signing — unsigned)
-        binding_hash = request_binding_hash(rack_request)
-        tx.add_output(::BSV::Transaction::TransactionOutput.new(
-                        satoshis: 0,
-                        locking_script: build_op_return_script(binding_hash)
-                      ))
-
-        [tx, payee_hex]
-      end
-
       def build_merkleworks_challenge(rack_request, route)
-        nonce = @nonce_provider.call(rack_request)
         config = X402.configuration
         payee_hex = derive_payee_hex
 
-        # Build template if Profile B
-        template, = build_proof_template(rack_request, route, nonce) if @nonce_key
+        nonce = @nonce_provider.call(rack_request, payee: payee_hex, amount: route.amount_sats)
+
+        # Profile B: provider returns a pre-signed partial_tx (binary)
+        template_binary = nonce[:partial_tx]
 
         attrs = {
           version: Challenge::CURRENT_VERSION,
@@ -127,8 +83,16 @@ module X402
           expires_at: Time.now.to_i + Challenge::DEFAULT_TTL
         }
 
-        # Profile B: include pre-signed template (not part of canonical hash)
-        attrs[:partial_tx_b64] = Base64.strict_encode64(template.to_binary) if template
+        if template_binary
+          # Deserialise the treasury's template and append OP_RETURN
+          tx = ::BSV::Transaction::Transaction.from_binary(template_binary)
+          binding_hash = request_binding_hash(rack_request)
+          tx.add_output(::BSV::Transaction::TransactionOutput.new(
+                          satoshis: 0,
+                          locking_script: build_op_return_script(binding_hash)
+                        ))
+          attrs[:partial_tx_b64] = Base64.strict_encode64(tx.to_binary)
+        end
 
         Challenge.new(attrs)
       end
@@ -154,7 +118,7 @@ module X402
         transaction = decode_transaction(proof)
         check_txid!(transaction, proof)
         check_nonce_input!(transaction, challenge)
-        verify_nonce_provenance!(transaction, challenge) if @nonce_key
+        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)
         transaction
@@ -163,8 +127,10 @@ module X402
       def decode_transaction(proof)
         raw = Base64.decode64(proof.rawtx_b64)
         ::BSV::Transaction::Transaction.from_binary(raw)
-      rescue StandardError => e
-        raise VerificationError, "failed to decode transaction: #{e.message}"
+      rescue VerificationError
+        raise
+      rescue StandardError
+        raise VerificationError, "failed to decode transaction"
       end
 
       def check_txid!(transaction, proof)
@@ -199,8 +165,8 @@ module X402
         end
       rescue VerificationError
         raise
-      rescue StandardError => e
-        raise VerificationError, "nonce provenance check failed: #{e.message}"
+      rescue StandardError
+        raise VerificationError, "nonce provenance check failed"
       end
 
       def verify_payment_output!(transaction, route, payee_hex)
@@ -214,19 +180,14 @@ module X402
       end
 
       def check_mempool!(txid)
-        @arc_client.status(txid)
-      rescue StandardError => e
-        raise VerificationError.new("mempool check failed: #{e.message}", status: 502)
-      end
-
-      # Validate that the nonce key matches the nonce UTXO's P2PKH locking script
-      def validate_nonce_key!(nonce)
-        expected_h160 = @nonce_key.public_key.hash160.unpack1("H*")
-        expected_script = "76a914#{expected_h160}88ac"
-        return if nonce[:locking_script_hex] == expected_script
+        response = @arc_client.status(txid)
+        return if ACCEPTABLE_MEMPOOL_STATUSES.include?(response.tx_status)
 
-        raise X402::ConfigurationError,
-              "nonce_key does not match nonce UTXO locking script"
+        raise VerificationError.new("transaction not yet visible in mempool", status: 402)
+      rescue VerificationError
+        raise
+      rescue StandardError
+        raise VerificationError.new("mempool check failed", status: 502)
       end
     end
   end

data/lib/x402/configuration.rb

@@ -6,12 +6,58 @@ module X402
 
     GATEWAY_METHODS = %i[challenge_headers proof_header_names settle!].freeze
 
-    attr_accessor :domain, :payee_locking_script_hex, :gateways
-    attr_reader :routes
+    PAY_GATEWAY_KNOWN_OPTS = %i[
+      arc_client payee_locking_script_hex arc_wait_for arc_timeout
+      binding_mode wallet challenge_secret
+    ].freeze
+
+    PROOF_GATEWAY_KNOWN_OPTS = %i[
+      arc_client payee_locking_script_hex nonce_provider
+      wallet challenge_secret
+    ].freeze
+
+    BRC105_GATEWAY_KNOWN_OPTS = %i[
+      arc_client key_deriver server_wif server_key prefix_store
+    ].freeze
+
+    GATEWAY_REGISTRY = {
+      pay_gateway: "X402::BSV::PayGateway",
+      proof_gateway: "X402::BSV::ProofGateway",
+      brc105_gateway: "X402::BSV::BRC105Gateway"
+    }.freeze
+
+    attr_accessor :domain, :payee_locking_script_hex, :gateways,
+                  :arc_url, :arc_api_key, :arc_client
+    attr_reader :routes, :gateway_specs
 
     def initialize
       @routes = []
       @gateways = []
+      @gateway_specs = []
+    end
+
+    # Record a gateway to be constructed later during +validate!+.
+    #
+    # @param name [Symbol] registered gateway name (e.g. +:pay_gateway+)
+    # @param options [Hash] options forwarded to the gateway constructor
+    # @raise [ConfigurationError] if the gateway name is not registered
+    def enable(name, **options)
+      class_name = GATEWAY_REGISTRY[name]
+      raise ConfigurationError, "unknown gateway: #{name.inspect}" unless class_name
+
+      @gateway_specs << [class_name, options]
+    end
+
+    # Returns a memoised ARC client instance. If +arc_client+ has been
+    # injected directly, that takes precedence. Otherwise, builds one
+    # from +arc_url+ (and optional +arc_api_key+).
+    #
+    # @return [BSV::Network::ARC]
+    # @raise [ConfigurationError] if +arc_url+ is nil and no +arc_client+ injected
+    def shared_arc_client
+      return @arc_client if @arc_client
+
+      @shared_arc_client ||= build_arc_client
     end
 
     # Register a protected route.
@@ -40,6 +86,7 @@ module X402
         raise ConfigurationError,
               "payee_locking_script_hex is required"
       end
+      build_gateways_from_specs! if gateways.empty? && !gateway_specs.empty?
       validate_gateways!
       raise ConfigurationError, "at least one route must be protected" if routes.empty?
     end
@@ -74,6 +121,89 @@ module X402
       end
     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_gateways_from_specs!
+      require_relative "bsv"
+      require "bsv-wallet"
+
+      @gateways = gateway_specs.map do |class_name, options|
+        klass = Object.const_get(class_name)
+        case class_name
+        when "X402::BSV::PayGateway" then build_pay_gateway(klass, options)
+        when "X402::BSV::ProofGateway" then build_proof_gateway(klass, options)
+        when "X402::BSV::BRC105Gateway" then build_brc105_gateway(klass, options)
+        end
+      end
+    end
+
+    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|
+        opts[key] = options[key] if options.key?(key)
+      end
+      klass.new(**opts)
+    end
+
+    def build_proof_gateway(klass, options)
+      reject_unknown_options!(:proof_gateway, options, PROOF_GATEWAY_KNOWN_OPTS)
+
+      raise ConfigurationError, "proof_gateway requires nonce_provider:" unless options.key?(:nonce_provider)
+
+      opts = { arc_client: options[:arc_client] || shared_arc_client,
+               payee_locking_script_hex: options[:payee_locking_script_hex] || payee_locking_script_hex,
+               nonce_provider: options[:nonce_provider] }
+
+      %i[wallet challenge_secret].each do |key|
+        opts[key] = options[key] if options.key?(key)
+      end
+      klass.new(**opts)
+    end
+
+    def build_brc105_gateway(klass, options) # rubocop:disable Metrics/PerceivedComplexity
+      reject_unknown_options!(:brc105_gateway, options, BRC105_GATEWAY_KNOWN_OPTS)
+
+      key_sources = %i[key_deriver server_wif server_key].select { |k| options.key?(k) }
+      if key_sources.size > 1
+        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
+                      ::BSV::Wallet::KeyDeriver.new(options[:server_key])
+                    end
+
+      klass.new(
+        key_deriver: key_deriver,
+        prefix_store: options[:prefix_store] || X402::BSV::PrefixStore::Memory.new,
+        arc_client: options[:arc_client] || shared_arc_client
+      )
+    end
+
+    # -- Option validation ---------------------------------------------------
+
+    def reject_unknown_options!(gateway_name, options, known)
+      unknown = options.keys - known
+      return if unknown.empty?
+
+      raise ConfigurationError,
+            "#{gateway_name}: unknown option(s): #{unknown.map(&:inspect).join(", ")}"
+    end
+
     def method_matches?(route_method, request_method)
       route_method == "*" || route_method == request_method.upcase
     end

data/lib/x402/middleware.rb

@@ -70,8 +70,8 @@ module X402
       error_response(e.status, e.reason)
     rescue X402::Error => e
       error_response(400, e.message)
-    rescue StandardError => e
-      error_response(500, "internal error: #{e.message}")
+    rescue StandardError
+      error_response(500, "internal error")
     end
 
     def error_response(status, reason)

data/lib/x402/protocol/base64url.rb

@@ -12,8 +12,8 @@ module X402
 
     def decode(data)
       Base64.urlsafe_decode64(data)
-    rescue ArgumentError => e
-      raise X402::Error, "invalid base64url: #{e.message}"
+    rescue ArgumentError
+      raise X402::Error, "invalid base64url encoding"
     end
   end
 end

data/lib/x402/protocol/challenge.rb

@@ -65,8 +65,8 @@ module X402
       json = Base64Url.decode(header_value)
       data = JSON.parse(json, symbolize_names: true)
       new(data)
-    rescue JSON::ParserError => e
-      raise X402::Error, "invalid challenge JSON: #{e.message}"
+    rescue JSON::ParserError
+      raise X402::Error, "invalid challenge JSON"
     end
   end
 end

data/lib/x402/protocol/proof.rb

@@ -20,8 +20,8 @@ module X402
         challenge_sha256: data[:challenge_sha256],
         payment: data[:payment]
       )
-    rescue JSON::ParserError => e
-      raise X402::Error, "invalid proof JSON: #{e.message}"
+    rescue JSON::ParserError
+      raise X402::Error, "invalid proof JSON"
     end
 
     # Convenience accessors for payment fields.

data/lib/x402/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: x402-rack
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: exe
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -29,28 +29,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: bsv-wallet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: json-canonicalization
   requirement: !ruby/object:Gem::Requirement
@@ -91,6 +91,7 @@ files:
 - ".claude/plans/20260326-rack-stack-architecture.md"
 - ".rspec"
 - ".rubocop.yml"
+- CHANGELOG.md
 - CLAUDE.md
 - DESIGN.md
 - LICENSE.txt