Skip to content

Class X402::PaymentObserver

Inherits: Object

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.).

Constants

DEFAULT_PROOF_HEADERS

Not documented.

Public Instance Methods

call(env)

  • @param env [Hash] Rack environment
  • @return [Array(Integer, Hash, Array)] Rack response triple (always passes through)

initialize(app, worker:, payee_locking_script_hex: = nil, recogniser: = nil, extractor: = nil, proof_headers: = DEFAULT_PROOF_HEADERS, on_payment: = nil)

  • @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 extractor [#call, nil] extracts a +BSV::Transaction::Transaction+ from a raw proof header value. Returns a Transaction or +nil+ to skip. Defaults to +CoinbaseV2Extractor+ (Base64-JSON envelope with +payload.rawtx+).
  • @param proof_headers [Array] 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
  • @return [PaymentObserver] a new instance of PaymentObserver