ruby-x402 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 781025ab8d5eea01d68d2123dbfc9976fe140fbddd291604b1068d62507af5db
+  data.tar.gz: 305bfd02dcff64cd373f0d5871d5c6f6fa1ba55a65f2eafc166668a310743af8
+SHA512:
+  metadata.gz: 13c3bda6931660daaf0a2fce995048128c3e4e74bb4c970d484b8eaee2331f7b096e11c5b527e656d287b26d81939237faa1e0cbf421d17e66b14d5cb6e23730
+  data.tar.gz: 07d5904a21f8b2b419f0ee63caaebe8c2964a5e6a6797dc7af406926ed52d9e6f67eed57cc72b0dbd689c1ab7dec11e9ff19adf0a271c24173042ec2c316d461

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## 0.1.0 (2025-11-10)
+
+- Rails integration:
+  - Railtie auto-inserts `X402::Rack::RequirePayment` and filters sensitive headers
+  - Installer generator with initializer template
+  - Optional controller concern `X402::Rails::ControllerConcern#require_x402_payment`
+  - Optional proxy facilitator Rails engine (`/verify`, `/settle`, `/discovery/resources`)
+- Config API: `X402.configure` with validated settings and defaults
+- Middleware: `:settle_async` mode using ActiveJob; `:verify_only` support
+- FacilitatorClient: timeouts, retries, error mapping, and robust JSON handling
+- Types: validation and error classes (`X402::Errors::*`)
+- Docs: Rails quickstart and `docs/rails.md`

data/README.md

@@ -0,0 +1,102 @@
+# ruby-x402
+
+Server-side Ruby implementation of the x402 payments protocol.
+
+Includes:
+
+- Rack middleware to require payments for routes
+- Facilitator client to verify and settle payments
+- Support for the `exact` scheme on EVM and Solana (SVM)
+
+This gem does not provide client-side signing. Use a facilitator (e.g., `https://x402.org/facilitator`) for verify/settle.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "ruby-x402"
+```
+
+## Quick start (Rack)
+
+```ruby
+use X402::Rack::RequirePayment, config: {
+  networks: ["base-sepolia", "solana-devnet"],
+  routes: {
+    "/paid" => {
+      evm: { amount: "1000000" },
+      svm: { amount: "1000000" }
+    }
+  },
+  evm: {
+    asset: "0x036CbD53842c...",
+    pay_to: "0xYourEvmAddress",
+    extra: { name: "USDC", version: "2" }
+  },
+  svm: {
+    asset: "EPjFWdd5Aufq...",
+    pay_to: "YourSolanaAddress",
+    extra: { fee_payer: "FacilitatorFeePayerAddress" }
+  },
+  facilitator: { url: "https://x402.org/facilitator" }
+}
+```
+
+## Quick start (Rails)
+
+1. Add the gem and bundle.
+2. Run the installer:
+
+```bash
+bin/rails g x402:install
+```
+
+This creates `config/initializers/x402.rb`. Adjust networks, pricing, and facilitator settings.
+
+3. (Optional) Mount the proxy facilitator engine to forward `/verify`, `/settle`, and discovery to an upstream:
+
+```ruby
+# config/routes.rb
+mount X402::Facilitator::Engine => "/x402"
+```
+
+4. Modes:
+- `:settle_sync` (default): verify then settle synchronously; returns `X-PAYMENT-RESPONSE` header
+- `:verify_only`: verify only, no settlement
+- `:settle_async`: verify then enqueue settlement via ActiveJob (if available)
+
+## Facilitator client
+
+```ruby
+client = X402::FacilitatorClient.new(
+  url: "https://x402.org/facilitator",
+  create_headers: -> {
+    { verify: { "Authorization" => "Bearer <token>" } }
+  }
+)
+
+payment = X402::Types::PaymentPayload.new(
+  x402_version: 1, scheme: "exact", network: "base-sepolia",
+  payload: { "authorization" => {}, "signature" => "0x" }
+)
+
+reqs = X402::Types::PaymentRequirements.new(
+  scheme: "exact", network: "base-sepolia", max_amount_required: "1000000",
+  resource: "/paid", description: "API access", mime_type: "application/json",
+  pay_to: "0x...", max_timeout_seconds: 60, asset: "0x...", extra: { "name" => "USDC", "version" => "2" }
+)
+
+verify = client.verify(payment: payment, payment_requirements: reqs)
+if verify.is_valid
+  settle = client.settle(payment: payment, payment_requirements: reqs)
+end
+```
+
+## Docs
+
+- See `docs/rails.md` for Rails integration details and troubleshooting.
+
+## License
+
+Apache-2.0

data/docs/rails.md

@@ -0,0 +1,60 @@
+# Rails integration
+
+## Install
+
+```bash
+bundle add ruby-x402
+bin/rails g x402:install
+```
+
+This adds `config/initializers/x402.rb` with sensible defaults.
+
+## Configuration
+
+Use `X402.configure`:
+
+```ruby
+X402.configure do |c|
+  c.networks = %w[base-sepolia solana-devnet]
+  c.routes = { "/paid" => { evm: { amount: "1000000" }, svm: { amount: "1000000" } } }
+  c.evm.asset = ENV["X402_EVM_ASSET"]
+  c.evm.pay_to = ENV["X402_EVM_PAY_TO"]
+  c.svm.asset = ENV["X402_SVM_ASSET"]
+  c.svm.pay_to = ENV["X402_SVM_PAY_TO"]
+  c.facilitator.url = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
+  c.facilitator.create_headers = -> { { verify: { "Authorization" => "Bearer #{ENV["X402_FACILITATOR_TOKEN"]}" } } }
+  c.mode = :settle_sync # or :verify_only, :settle_async
+end
+```
+
+The Railtie auto-inserts the `X402::Rack::RequirePayment` middleware using the configured settings.
+
+## Proxy facilitator engine (optional)
+
+Mount the engine to forward requests to a configured upstream facilitator:
+
+```ruby
+# config/routes.rb
+mount X402::Facilitator::Engine => "/x402"
+```
+
+Endpoints:
+- POST `/x402/verify`
+- POST `/x402/settle`
+- GET `/x402/discovery/resources`
+
+## Modes
+- `:settle_sync` (default): verify then settle synchronously; sets `X-PAYMENT-RESPONSE`
+- `:verify_only`: verify only
+- `:settle_async`: verify, then enqueue settlement with `ActiveJob` if present
+
+## Security and logging
+- `X-PAYMENT` and `X-PAYMENT-RESPONSE` are filtered from Rails logs by default.
+- CORS: Ensure `Access-Control-Expose-Headers` includes `X-PAYMENT-RESPONSE` (middleware sets it).
+
+## Troubleshooting
+- `invalid_x402_version`, `invalid_network`, `invalid_scheme`: Check payload formation and network selection.
+- `unsupported network` during boot: Ensure `c.networks` is one of `X402::Types::Networks::ALL`.
+- Settlement not appearing with `:settle_async`: Ensure ActiveJob queue is running, or use `:settle_sync`.
+
+

data/lib/generators/x402/install_generator.rb

@@ -0,0 +1,21 @@
+begin
+  require "rails/generators"
+rescue LoadError
+  # Rails not available
+end
+
+module X402
+  module Generators
+    class InstallGenerator < (defined?(Rails::Generators::Base) ? Rails::Generators::Base : Object)
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        return unless defined?(Rails::Generators::Base)
+        template "x402.rb", "config/initializers/x402.rb"
+      end
+    end
+  end
+end
+
+
+

data/lib/generators/x402/templates/x402.rb

@@ -0,0 +1,31 @@
+X402.configure do |c|
+  c.networks = %w[base-sepolia solana-devnet]
+  c.routes = {
+    "/paid" => {
+      evm: { amount: "1000000" },
+      svm: { amount: "1000000" }
+    }
+  }
+
+  # EVM network settings
+  c.evm.asset = ENV.fetch("X402_EVM_ASSET", nil)
+  c.evm.pay_to = ENV.fetch("X402_EVM_PAY_TO", nil)
+  c.evm.extra = { name: "USDC", version: "2" }
+
+  # SVM network settings
+  c.svm.asset = ENV.fetch("X402_SVM_ASSET", nil)
+  c.svm.pay_to = ENV.fetch("X402_SVM_PAY_TO", nil)
+  c.svm.extra = { fee_payer: ENV.fetch("X402_SVM_FEE_PAYER", nil) }.compact
+
+  # Facilitator settings
+  c.facilitator.url = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/protected")
+  c.facilitator.create_headers = lambda {
+    token = ENV["X402_FACILITATOR_TOKEN"]
+    token ? { verify: { "Authorization" => "Bearer #{token}" }, settle: { "Authorization" => "Bearer #{token}" } } : {}
+  }
+
+  c.mode = :settle_sync # :verify_only or :settle_async
+  c.max_timeout_seconds = 60
+end
+
+

data/lib/x402/config.rb

@@ -0,0 +1,120 @@
+require_relative "types/networks"
+require_relative "errors"
+
+module X402
+  class Config
+    DEFAULT_MODE = :settle_sync
+    DEFAULT_TIMEOUT = 60
+
+    class NetworkSettings
+      attr_accessor :asset, :pay_to, :extra
+
+      def initialize
+        @asset = nil
+        @pay_to = nil
+        @extra = {}
+      end
+
+      def to_h
+        {
+          asset: asset,
+          pay_to: pay_to,
+          extra: extra || {}
+        }
+      end
+    end
+
+    class FacilitatorSettings
+      attr_accessor :url, :create_headers
+
+      def initialize
+        @url = X402::FacilitatorClient::DEFAULT_URL
+        @create_headers = nil
+      end
+
+      def to_h
+        {
+          url: url,
+          create_headers: create_headers
+        }
+      end
+    end
+
+    attr_accessor :networks, :routes, :mode, :max_timeout_seconds
+    attr_reader :evm, :svm, :facilitator
+
+    def initialize
+      @networks = []
+      @routes = {}
+      @evm = NetworkSettings.new
+      @svm = NetworkSettings.new
+      @facilitator = FacilitatorSettings.new
+      @mode = DEFAULT_MODE
+      @max_timeout_seconds = DEFAULT_TIMEOUT
+    end
+
+    def routes=(value)
+      @routes = deep_symbolize(value || {})
+    end
+
+    def validate!
+      unless mode.is_a?(Symbol) && %i[settle_sync verify_only settle_async].include?(mode)
+        raise X402::Errors::ConfigurationError, "Invalid mode: #{mode.inspect}"
+      end
+      unless max_timeout_seconds.is_a?(Integer) && max_timeout_seconds.positive?
+        raise X402::Errors::ConfigurationError, "max_timeout_seconds must be a positive Integer"
+      end
+
+      networks.each do |n|
+        unless X402::Types::Networks::ALL.include?(n)
+          raise X402::Errors::ValidationError, "Unsupported network: #{n}"
+        end
+      end
+
+      if networks.any? { |n| n.include?("base") }
+        %i[asset pay_to].each do |k|
+          v = evm.public_send(k)
+          raise X402::Errors::ConfigurationError, "EVM #{k} must be configured" if v.nil? || v.to_s.empty?
+        end
+      end
+      if networks.any? { |n| n.start_with?("solana") }
+        %i[asset pay_to].each do |k|
+          v = svm.public_send(k)
+          raise X402::Errors::ConfigurationError, "SVM #{k} must be configured" if v.nil? || v.to_s.empty?
+        end
+      end
+      self
+    end
+
+    def to_h
+      {
+        networks: networks,
+        routes: routes,
+        evm: evm.to_h,
+        svm: svm.to_h,
+        facilitator: facilitator.to_h,
+        mode: mode,
+        max_timeout_seconds: max_timeout_seconds
+      }
+    end
+
+    private
+
+    def deep_symbolize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), acc|
+          key = (k.to_sym rescue k) || k
+          acc[key] = deep_symbolize(v)
+        end
+      when Array
+        obj.map { |v| deep_symbolize(v) }
+      else
+        obj
+      end
+    end
+  end
+end
+
+
+

data/lib/x402/encoding.rb

@@ -0,0 +1,18 @@
+require "base64"
+require "json"
+
+module X402
+  module Encoding
+    module_function
+
+    def encode_header(hash)
+      json = JSON.generate(hash)
+      Base64.strict_encode64(json)
+    end
+
+    def decode_header(base64_string)
+      json = Base64.decode64(base64_string.to_s)
+      JSON.parse(json)
+    end
+  end
+end

data/lib/x402/errors.rb

@@ -0,0 +1,22 @@
+module X402
+  module Errors
+    class BaseError < StandardError; end
+
+    class ConfigurationError < BaseError; end
+    class ValidationError < BaseError; end
+
+    class NetworkError < BaseError; end
+    class TimeoutError < NetworkError; end
+    class HttpError < NetworkError
+      attr_reader :status, :body
+      def initialize(message = "HTTP error", status: nil, body: nil)
+        @status = status
+        @body = body
+        super(message)
+      end
+    end
+    class ParseError < BaseError; end
+
+    class UnsupportedError < BaseError; end
+  end
+end

data/lib/x402/facilitator/engine.rb

@@ -0,0 +1,24 @@
+begin
+  require "rails/engine"
+rescue LoadError
+  # Rails not available
+end
+
+module X402
+  module Facilitator
+    class Engine < ::Rails::Engine
+      isolate_namespace X402::Facilitator
+
+      initializer "x402.facilitator.routes" do
+        X402::Facilitator::Engine.routes.draw do
+          post "/verify", to: "requests#verify"
+          post "/settle", to: "requests#settle"
+          get "/discovery/resources", to: "requests#list"
+        end
+      end
+    end
+  end
+end
+
+
+

data/lib/x402/facilitator/requests_controller.rb

@@ -0,0 +1,68 @@
+begin
+  require "action_controller/railtie"
+rescue LoadError
+  # Rails not available
+end
+
+require_relative "../facilitator_client"
+require_relative "../types/payment_payload"
+require_relative "../types/payment_requirements"
+require_relative "../errors"
+
+module X402
+  module Facilitator
+    class RequestsController < (defined?(::ActionController::API) ? ::ActionController::API : ::ActionController::Base)
+      def verify
+        client = build_client
+        payload, reqs = parse_payload_and_requirements
+        render json: client.verify(payment: payload, payment_requirements: reqs).to_h
+      rescue X402::Errors::BaseError => e
+        render json: { isValid: false, invalidReason: e.class.name.split("::").last.underscore }, status: :bad_request
+      rescue StandardError => e
+        render json: { isValid: false, invalidReason: "unexpected_verify_error" }, status: :internal_server_error
+      end
+
+      def settle
+        client = build_client
+        payload, reqs = parse_payload_and_requirements
+        render json: client.settle(payment: payload, payment_requirements: reqs).to_h
+      rescue X402::Errors::BaseError => e
+        render json: { success: false, errorReason: e.class.name.split("::").last.underscore }, status: :bad_request
+      rescue StandardError => e
+        render json: { success: false, errorReason: "unexpected_settle_error" }, status: :internal_server_error
+      end
+
+      def list
+        client = build_client
+        items = client.list(params: request.query_parameters)
+        render json: items
+      rescue X402::Errors::BaseError => e
+        render json: { error: e.message }, status: :bad_request
+      rescue StandardError => e
+        render json: { error: "unexpected_list_error" }, status: :internal_server_error
+      end
+
+      private
+
+      def build_client
+        ::X402::FacilitatorClient.new(
+          url: ::X402.config.facilitator.url,
+          create_headers: ::X402.config.facilitator.create_headers
+        )
+      end
+
+      def parse_payload_and_requirements
+        body = request.request_parameters.presence || JSON.parse(request.raw_post)
+        payload = body["paymentPayload"] || body["payment_payload"]
+        requirements = body["paymentRequirements"] || body["payment_requirements"]
+        [
+          ::X402::Types::PaymentPayload.from_hash(payload),
+          ::X402::Types::PaymentRequirements.from_hash(requirements)
+        ]
+      end
+    end
+  end
+end
+
+
+

data/lib/x402/facilitator_client.rb

@@ -0,0 +1,155 @@
+require "net/http"
+require "uri"
+require "json"
+require_relative "types/payment_payload"
+require_relative "types/payment_requirements"
+require_relative "types/responses"
+require_relative "errors"
+
+module X402
+  class FacilitatorClient
+    DEFAULT_URL = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/protected").freeze
+
+    def initialize(url: DEFAULT_URL, create_headers: nil, open_timeout: 5, read_timeout: 10, write_timeout: 5, retry_count: 1)
+      raise ArgumentError, "Invalid URL #{url}" unless url.to_s.start_with?("http://", "https://")
+      @base_url = url.end_with?("/") ? url[0..-2] : url
+      @create_headers = create_headers # -> { verify: {..}, settle: {..}, list: {..} }
+      @open_timeout = Integer(open_timeout)
+      @read_timeout = Integer(read_timeout)
+      @write_timeout = Integer(write_timeout) rescue 5
+      @retry_count = Integer(retry_count)
+    end
+
+    def verify(payment:, payment_requirements:)
+      body = {
+        "x402Version" => normalize_payload(payment).x402_version,
+        "paymentPayload" => normalize_payload(payment).to_h,
+        "paymentRequirements" => normalize_requirements(payment_requirements).to_h
+      }
+      headers = base_headers.merge(endpoint_headers(:verify))
+      data = post_json("#{@base_url}/verify", body, headers)
+      Types::VerifyResponse.from_hash(data)
+    end
+
+    def settle(payment:, payment_requirements:)
+      body = {
+        "x402Version" => normalize_payload(payment).x402_version,
+        "paymentPayload" => normalize_payload(payment).to_h,
+        "paymentRequirements" => normalize_requirements(payment_requirements).to_h
+      }
+      headers = base_headers.merge(endpoint_headers(:settle))
+      data = post_json("#{@base_url}/settle", body, headers)
+      Types::SettleResponse.from_hash(data)
+    end
+
+    def list(params: {})
+      headers = base_headers.merge(endpoint_headers(:list))
+      uri = URI("#{@base_url}/discovery/resources")
+      uri.query = URI.encode_www_form(params.transform_keys { |k| camelize(k.to_s) })
+      res = with_retries { http_get(uri, headers) }
+      ensure_success!(res)
+      parse_json(res.body)
+    end
+
+    private
+
+    def base_headers
+      { "Content-Type" => "application/json" }
+    end
+
+    def endpoint_headers(kind)
+      return {} unless @create_headers
+      custom = @create_headers.call
+      (custom[kind] || {}) || {}
+    end
+
+    def http_post(uri, body, headers)
+      uri = URI(uri)
+      req = Net::HTTP::Post.new(uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body
+      perform_http(uri, req)
+    end
+
+    def http_get(uri, headers)
+      req = Net::HTTP::Get.new(uri)
+      headers.each { |k, v| req[k] = v }
+      perform_http(uri, req)
+    end
+
+    def post_json(uri, obj, headers)
+      res = http_post(uri, JSON.generate(obj), headers)
+      ensure_success!(res)
+      parse_json(res.body)
+    rescue JSON::ParserError => e
+      raise X402::Errors::ParseError, "Invalid JSON response: #{e.message}"
+    rescue Timeout::Error => e
+      raise X402::Errors::TimeoutError, e.message
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+      raise X402::Errors::NetworkError, e.message
+    end
+
+    def normalize_payload(obj)
+      case obj
+      when Types::PaymentPayload then obj
+      when String then Types::PaymentPayload.from_json(obj)
+      when Hash then Types::PaymentPayload.from_hash(obj)
+      else
+        raise ArgumentError, "Unsupported payment payload type: #{obj.class}"
+      end
+    end
+
+    def normalize_requirements(obj)
+      case obj
+      when Types::PaymentRequirements then obj
+      when String then Types::PaymentRequirements.from_json(obj)
+      when Hash then Types::PaymentRequirements.from_hash(obj)
+      else
+        raise ArgumentError, "Unsupported payment requirements type: #{obj.class}"
+      end
+    end
+
+    def camelize(key)
+      parts = key.split("_")
+      parts[0] + parts[1..].map(&:capitalize).join
+    end
+
+    def perform_http(uri, req)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.open_timeout = @open_timeout if http.respond_to?(:open_timeout=)
+        http.read_timeout = @read_timeout if http.respond_to?(:read_timeout=)
+        http.write_timeout = @write_timeout if http.respond_to?(:write_timeout=)
+        http.request(req)
+      end
+    rescue Timeout::Error => e
+      raise X402::Errors::TimeoutError, e.message
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+      raise X402::Errors::NetworkError, e.message
+    end
+
+    def with_retries
+      attempts = 0
+      begin
+        yield
+      rescue X402::Errors::TimeoutError, X402::Errors::NetworkError => e
+        attempts += 1
+        raise e if attempts > @retry_count
+        sleep(0.2 * attempts)
+        retry
+      end
+    end
+
+    def ensure_success!(res)
+      return if res.is_a?(Net::HTTPSuccess)
+      raise X402::Errors::HttpError.new("HTTP #{res.code}", status: res.code.to_i, body: res.body)
+    end
+
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise X402::Errors::ParseError, "Invalid JSON response: #{e.message}"
+    end
+  end
+end
+
+