Class: X402::PaymentObserver

Inherits:
Object
  • Object
show all
Defined in:
lib/x402/payment_observer.rb

Overview

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

Defined Under Namespace

Classes: CoinbaseV2Extractor, StaticRecogniser

Constant Summary collapse

DEFAULT_PROOF_HEADERS = 
%w[Payment-Signature].freeze

Instance Method Summary collapse

Constructor Details

#initialize(app, worker:, payee_locking_script_hex: nil, recogniser: nil, extractor: nil, proof_headers: DEFAULT_PROOF_HEADERS, on_payment: nil) ⇒ PaymentObserver

Returns a new instance of PaymentObserver.

Parameters:

  • app (#call) —

    next Rack app in the stack

  • worker (#enqueue) —

    settlement worker for background broadcast

  • payee_locking_script_hex (String, nil) (defaults to: nil) —

    static payee script hex

  • recogniser (#ours?, nil) (defaults to: nil) —

    object that recognises derived payment addresses. Takes precedence over +payee_locking_script_hex+ when both are provided.

  • extractor (#call, nil) (defaults to: 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+).

  • proof_headers (Array<String>) (defaults to: DEFAULT_PROOF_HEADERS) —

    HTTP header names to watch for payments

  • on_payment (#call, nil) (defaults to: nil) —

    optional callback invoked with the raw tx binary after successful enqueue, for application-level tracking



48
49
50
51
52
53
54
55
56
 
# File 'lib/x402/payment_observer.rb', line 48

def initialize(app, worker:, payee_locking_script_hex: nil, recogniser: nil,
               extractor: nil, proof_headers: DEFAULT_PROOF_HEADERS, on_payment: nil)
  @app = app
  @worker = worker
  @recogniser = build_recogniser(recogniser, payee_locking_script_hex)
  @extractor = build_extractor(extractor)
  @proof_headers = proof_headers
  @on_payment = on_payment
end

Instance Method Details

#call(env) ⇒ Array(Integer, Hash, Array)

Returns Rack response triple (always passes through).

Parameters:

  • env (Hash) —

    Rack environment

Returns:

  • (Array(Integer, Hash, Array)) —

    Rack response triple (always passes through)



60
61
62
63
 
# File 'lib/x402/payment_observer.rb', line 60

def call(env)
  observe_payment(env)
  @app.call(env)
end