x402-rails 0.2.1 → 1.0.0

data/lib/x402/payment_payload.rb

@@ -2,14 +2,23 @@
 
 module X402
   class PaymentPayload
-    attr_accessor :x402_version, :scheme, :network, :payload
+    attr_accessor :x402_version, :scheme, :network, :payload, :accepted, :resource_info
 
     def initialize(attributes = {})
       attrs = attributes.with_indifferent_access
 
-      @x402_version = attrs[:x402Version] || attrs[:x402_version] || 1
-      @scheme = attrs[:scheme]
-      @network = attrs[:network]
+      @x402_version = (attrs[:x402Version] || attrs[:x402_version] || 1).to_i
+      @accepted = attrs[:accepted]
+      @resource_info = attrs[:resource]
+
+      if @accepted
+        @scheme = @accepted.with_indifferent_access[:scheme]
+        @network = normalize_network(@accepted.with_indifferent_access[:network])
+      else
+        @scheme = attrs[:scheme]
+        @network = normalize_network(attrs[:network])
+      end
+
       @payload = attrs[:payload]
     end
 
@@ -25,49 +34,112 @@ module X402
       end
     end
 
+    def solana_chain?
+      X402.solana_chain?(network)
+    end
+
+    def evm_chain?
+      !solana_chain?
+    end
+
+    def transaction
+      return nil unless solana_chain?
+      payload&.with_indifferent_access&.[](:transaction)
+    end
+
     def authorization
+      return nil if solana_chain?
       @authorization ||= payload&.with_indifferent_access&.[](:authorization)
     end
 
     def signature
+      return nil if solana_chain?
       payload&.with_indifferent_access&.[](:signature)
     end
 
     def from_address
+      return nil if solana_chain?
       authorization&.with_indifferent_access&.[](:from)
     end
 
     def to_address
+      return nil if solana_chain?
       authorization&.with_indifferent_access&.[](:to)
     end
 
     def value
+      return nil if solana_chain?
       authorization&.with_indifferent_access&.[](:value)
     end
 
     def valid_after
+      return nil if solana_chain?
       authorization&.with_indifferent_access&.[](:validAfter) || authorization&.with_indifferent_access&.[](:valid_after)
     end
 
     def valid_before
+      return nil if solana_chain?
       authorization&.with_indifferent_access&.[](:validBefore) || authorization&.with_indifferent_access&.[](:valid_before)
     end
 
     def nonce
+      return nil if solana_chain?
       authorization&.with_indifferent_access&.[](:nonce)
     end
 
     def to_h
-      {
-        x402Version: x402_version,
-        scheme: scheme,
-        network: network,
-        payload: payload
-      }
+      version_strategy = X402::Versions.for(x402_version)
+
+      if x402_version >= 2
+        base = {
+          x402Version: x402_version,
+          accepted: format_accepted_for_version(version_strategy),
+          payload: payload,
+          extensions: {}
+        }
+        base[:resource] = resource_info if resource_info
+        base
+      else
+        {
+          x402Version: x402_version,
+          scheme: scheme,
+          network: version_strategy.format_network(network),
+          payload: payload
+        }
+      end
     end
 
     def to_json(*args)
       to_h.to_json(*args)
     end
+
+    private
+
+    def normalize_network(network_value)
+      return network_value unless network_value
+
+      if network_value.to_s.include?(":")
+        X402.from_caip2(network_value)
+      else
+        network_value
+      end
+    rescue X402::ConfigurationError
+      network_value
+    end
+
+    def format_accepted_for_version(version_strategy)
+      return nil unless accepted
+
+      acc = accepted.with_indifferent_access
+      {
+        scheme: acc[:scheme],
+        network: version_strategy.format_network(network),
+        amount: (acc[:amount] || acc[:maxAmountRequired]).to_s,
+        asset: acc[:asset],
+        payTo: acc[:payTo] || acc[:pay_to],
+        maxTimeoutSeconds: acc[:maxTimeoutSeconds] || acc[:max_timeout_seconds],
+        extra: acc[:extra]
+      }.compact
+    end
   end
 end

data/lib/x402/payment_requirement.rb

@@ -2,14 +2,15 @@
 
 module X402
   class PaymentRequirement
-    attr_accessor :scheme, :network, :max_amount_required, :asset, :pay_to, :resource, :description, :max_timeout_seconds, :mime_type, :output_schema, :extra
+    attr_accessor :scheme, :network, :amount, :asset, :pay_to, :resource, :description,
+                  :max_timeout_seconds, :mime_type, :output_schema, :extra, :version
 
     def initialize(attributes = {})
       attrs = attributes.with_indifferent_access
 
       @scheme = attrs[:scheme] || "exact"
-      @network = attrs[:network]
-      @max_amount_required = attrs[:maxAmountRequired] || attrs[:max_amount_required]
+      @network = normalize_network(attrs[:network])
+      @amount = attrs[:maxAmountRequired] || attrs[:max_amount_required] || attrs[:amount]
       @asset = attrs[:asset]
       @pay_to = attrs[:payTo] || attrs[:pay_to]
       @resource = attrs[:resource]
@@ -18,27 +19,47 @@ module X402
       @mime_type = attrs[:mimeType] || attrs[:mime_type] || "application/json"
       @output_schema = attrs[:outputSchema] || attrs[:output_schema]
       @extra = attrs[:extra]
+      @version = attrs[:version]
     end
 
-    def to_h
-      h = {
+    def max_amount_required
+      @amount
+    end
+
+    def to_h(version: nil)
+      v = version || @version || X402.configuration.version
+      version_strategy = X402::Versions.for(v)
+
+      version_strategy.format_requirement(
         scheme: scheme,
         network: network,
-        maxAmountRequired: max_amount_required.to_s,
+        amount: amount,
         asset: asset,
-        payTo: pay_to,
+        pay_to: pay_to,
         resource: resource,
         description: description,
-        maxTimeoutSeconds: max_timeout_seconds,
-        mimeType: mime_type
-      }
-      h[:outputSchema] = output_schema if output_schema
-      h[:extra] = extra if extra
-      h
+        max_timeout_seconds: max_timeout_seconds,
+        mime_type: mime_type,
+        extra: extra
+      )
     end
 
     def to_json(*args)
       to_h.to_json(*args)
     end
+
+    private
+
+    def normalize_network(network_value)
+      return network_value unless network_value
+
+      if network_value.to_s.include?(":")
+        X402.from_caip2(network_value)
+      else
+        network_value
+      end
+    rescue X402::ConfigurationError
+      network_value
+    end
   end
 end

data/lib/x402/payment_validator.rb

@@ -19,17 +19,26 @@ module X402
         return validation_error("Network mismatch: expected #{requirement.network}, got #{payment_payload.network}")
       end
 
-      # Validate recipient address
-      unless payment_payload.to_address&.downcase == requirement.pay_to&.downcase
-        return validation_error("Recipient mismatch: expected #{requirement.pay_to}, got #{payment_payload.to_address}")
-      end
+      # For EVM chains, validate recipient and amount locally before calling facilitator
+      # For Solana chains, the facilitator handles all validation of the transaction
+      if payment_payload.evm_chain?
+        # Validate recipient address
+        unless payment_payload.to_address&.downcase == requirement.pay_to&.downcase
+          return validation_error("Recipient mismatch: expected #{requirement.pay_to}, got #{payment_payload.to_address}")
+        end
 
-      # Validate amount
-      payment_value = payment_payload.value.to_i
-      required_value = requirement.max_amount_required.to_i
+        # Validate amount
+        payment_value = payment_payload.value.to_i
+        required_value = requirement.max_amount_required.to_i
 
-      if payment_value < required_value
-        return validation_error("Insufficient amount: expected at least #{required_value}, got #{payment_value}")
+        if payment_value < required_value
+          return validation_error("Insufficient amount: expected at least #{required_value}, got #{payment_value}")
+        end
+      else
+        # Solana: verify transaction payload exists
+        unless payment_payload.transaction
+          return validation_error("Solana payment missing transaction payload")
+        end
       end
 
       # Call facilitator to verify payment (does NOT settle on blockchain yet)

data/lib/x402/rails/controller_extensions.rb

@@ -11,110 +11,215 @@ module X402
 
       def x402_paywall(options = {})
         amount = options[:amount] or raise ArgumentError, "amount is required"
-        chain = options[:chain] || X402.configuration.chain
-        currency = options[:currency] || X402.configuration.currency
+        chain = options[:chain]
+        currency = options[:currency]
+        protocol_version = options[:version] || X402.configuration.version
+        wallet_address = options[:wallet_address]
+        fee_payer = options[:fee_payer]
+        accepts = options[:accepts]
 
-        # Check if payment header is present
-        payment_header = request.headers["X-PAYMENT"]
+        begin
+          version_strategy = X402::Versions.for(protocol_version)
+        rescue X402::ConfigurationError => e
+          return render_configuration_error(e.message)
+        end
+
+        payment_header = request.headers[version_strategy.payment_header_name]
 
         if payment_header.nil? || payment_header.empty?
-          # No payment provided, return 402 with requirements
-          return render_payment_required(amount, chain, currency)
+          return render_payment_required(
+            amount,
+            chain: chain,
+            currency: currency,
+            version: protocol_version,
+            wallet_address: wallet_address,
+            fee_payer: fee_payer,
+            accepts: accepts
+          )
         end
 
-        # Payment provided, validate it
-        process_payment(payment_header, amount, chain, currency)
+        process_payment(
+          payment_header, amount,
+          chain: chain,
+          currency: currency,
+          version: protocol_version,
+          wallet_address: wallet_address,
+          fee_payer: fee_payer,
+          accepts: accepts
+        )
       end
 
       private
 
-      def generate_payment_required_response(amount, chain, currency, error_message = nil)
+      def generate_payment_required_response(amount, error_message = nil,
+                                              chain: nil, currency: nil, version: nil,
+                                              wallet_address: nil, fee_payer: nil, accepts: nil)
+        protocol_version = version || X402.configuration.version
+
         requirement_response = X402::RequirementGenerator.generate(
           amount: amount,
           resource: request.original_url,
           description: "Payment required for #{request.path}",
           chain: chain,
-          currency: currency
+          currency: currency,
+          version: protocol_version,
+          wallet_address: wallet_address,
+          fee_payer: fee_payer,
+          accepts: accepts
         )
         requirement_response[:error] = error_message if error_message
         requirement_response
       end
 
-      def render_payment_required(amount, chain, currency)
-        requirement_response = generate_payment_required_response(amount, chain, currency)
+      def render_payment_required(amount, chain: nil, currency: nil, version: nil,
+                                   wallet_address: nil, fee_payer: nil, accepts: nil)
+        protocol_version = version || X402.configuration.version
+        version_strategy = X402::Versions.for(protocol_version)
+
+        requirement_response = generate_payment_required_response(
+          amount,
+          chain: chain,
+          currency: currency,
+          version: protocol_version,
+          wallet_address: wallet_address,
+          fee_payer: fee_payer,
+          accepts: accepts
+        )
+
+        render_402_response(requirement_response, version_strategy)
+      end
+
+      def render_402_response(requirement_response, version_strategy)
+        if version_strategy.requirement_header_name
+          response.headers[version_strategy.requirement_header_name] =
+            Base64.strict_encode64(requirement_response.to_json)
+        end
+        render json: requirement_response, status: :payment_required
+      end
 
-        # Detect if request is from browser or API client
-        # if browser_request?
-        #   render_html_paywall(requirement_response)
-        # else
-          render json: requirement_response, status: :payment_required
-        # end
+      def render_configuration_error(message)
+        # Use V1 as a safe fallback when version is invalid to avoid recursive errors
+        fallback_strategy = X402::Versions::V1.new
+        error_response = {
+          x402Version: 1,
+          error: "Configuration error: #{message}",
+          accepts: []
+        }
+        render_402_response(error_response, fallback_strategy)
       end
 
-      def process_payment(payment_header, amount, chain, currency)
-        # Parse payment payload
+      def process_payment(payment_header, amount, chain: nil, currency: nil,
+                          version: nil, wallet_address: nil, fee_payer: nil, accepts: nil)
+        protocol_version = version || X402.configuration.version
+        version_strategy = X402::Versions.for(protocol_version)
+
         payment_payload = X402::PaymentPayload.from_header(payment_header)
 
-        # Generate requirement for validation (must match the 402 response exactly!)
         requirement_data = X402::RequirementGenerator.generate(
           amount: amount,
           resource: request.original_url,
           description: "Payment required for #{request.path}",
           chain: chain,
-          currency: currency
+          currency: currency,
+          version: protocol_version,
+          wallet_address: wallet_address,
+          fee_payer: fee_payer,
+          accepts: accepts
         )
 
-        requirement = X402::PaymentRequirement.new(requirement_data[:accepts].first)
+        matching_accept = find_matching_accept(requirement_data[:accepts], payment_payload, version_strategy)
+
+        unless matching_accept
+          requirement_response = generate_payment_required_response(
+            amount, "Payment network not accepted: #{payment_payload.network}",
+            chain: chain, currency: currency, version: protocol_version,
+            wallet_address: wallet_address, fee_payer: fee_payer, accepts: accepts
+          )
+          return render_402_response(requirement_response, version_strategy)
+        end
+
+        resource_info = requirement_data[:resource] || {}
+        additional_attrs = { version: protocol_version }
+        additional_attrs[:resource] = resource_info[:url] if resource_info[:url]
+        additional_attrs[:description] = resource_info[:description] if resource_info[:description]
+        additional_attrs[:mime_type] = resource_info[:mimeType] if resource_info[:mimeType]
+        requirement_attrs = matching_accept.merge(additional_attrs)
+        requirement = X402::PaymentRequirement.new(requirement_attrs)
 
-        # Validate payment (verify signature, but don't settle on blockchain yet)
         validator = X402::PaymentValidator.new
         validation_result = validator.validate(payment_payload, requirement)
 
         unless validation_result[:valid]
-          requirement_response = generate_payment_required_response(amount, chain, currency, validation_result[:error])
-          return render json: requirement_response, status: :payment_required
+          requirement_response = generate_payment_required_response(
+            amount, validation_result[:error],
+            chain: chain, currency: currency, version: protocol_version,
+            wallet_address: wallet_address, fee_payer: fee_payer, accepts: accepts
+          )
+          return render_402_response(requirement_response, version_strategy)
         end
 
-        # Store payment info and requirement in request environment
         request.env["x402.payment"] = {
           payer: validation_result[:payer],
           amount: payment_payload.value,
           network: payment_payload.network,
           payload: payment_payload,
-          requirement: requirement
+          requirement: requirement,
+          version: protocol_version
         }
 
-        # If non-optimistic mode, settle payment synchronously before continuing
         unless X402.configuration.optimistic
           settlement_result = settle_payment_now
 
-          # If settlement failed, abort and return 402 with payment requirements
           if settlement_result.nil? || !settlement_result.success?
             error_message = settlement_result&.error_reason || "Settlement failed"
-            requirement_response = generate_payment_required_response(amount, chain, currency, "failed to settle payment: #{error_message}")
-            return render json: requirement_response, status: :payment_required
+            requirement_response = generate_payment_required_response(
+              amount, "failed to settle payment: #{error_message}",
+              chain: chain, currency: currency, version: protocol_version,
+              wallet_address: wallet_address, fee_payer: fee_payer, accepts: accepts
+            )
+            return render_402_response(requirement_response, version_strategy)
           end
         end
 
-        # Payment verified, continue with action
-        # In optimistic mode, settlement will happen automatically via after_action callback
       rescue X402::InvalidPaymentError => e
-        requirement_response = generate_payment_required_response(amount, chain, currency, "Invalid payment: #{e.message}")
-        render json: requirement_response, status: :payment_required
+        requirement_response = generate_payment_required_response(
+          amount, "Invalid payment: #{e.message}",
+          chain: chain, currency: currency, version: protocol_version,
+          wallet_address: wallet_address, fee_payer: fee_payer, accepts: accepts
+        )
+        render_402_response(requirement_response, version_strategy)
       rescue X402::FacilitatorError => e
-        requirement_response = generate_payment_required_response(amount, chain, currency, "Verification error: #{e.message}")
-        render json: requirement_response, status: :payment_required
+        requirement_response = generate_payment_required_response(
+          amount, "Verification error: #{e.message}",
+          chain: chain, currency: currency, version: protocol_version,
+          wallet_address: wallet_address, fee_payer: fee_payer, accepts: accepts
+        )
+        render_402_response(requirement_response, version_strategy)
+      rescue X402::ConfigurationError => e
+        render_configuration_error(e.message)
+      end
+
+      def find_matching_accept(accepts, payment_payload, version_strategy)
+        payment_network = payment_payload.network
+
+        accepts.find do |accept|
+          accept_network = accept[:network]
+          next false unless accept_network.present?
+
+          if accept_network.to_s.include?(":")
+            version_strategy.parse_network(accept_network) == payment_network
+          else
+            accept_network == payment_network
+          end
+        end
       end
 
       def settle_x402_payment_if_needed
-        # Only run in optimistic mode (non-optimistic settles synchronously)
         return unless X402.configuration.optimistic
 
-        # Only settle if payment was verified
         payment_info = request.env["x402.payment"]
         return unless payment_info
 
-        # Only settle if response is 2xx (success)
         return unless response.status >= 200 && response.status < 300
 
         perform_settlement(payment_info)
@@ -127,7 +232,6 @@ module X402
         ::Rails.logger.info("=== X402 Non-Optimistic Settlement (before response) ===")
         settlement_result = perform_settlement(payment_info)
 
-        # Store settlement result for later use (e.g., adding to response body)
         request.env["x402.settlement_result"] = settlement_result
         settlement_result
       end
@@ -141,19 +245,19 @@ module X402
           ::Rails.logger.info("Requirement class: #{payment_info[:requirement].class}")
           ::Rails.logger.info("Requirement hash: #{payment_info[:requirement].to_h.inspect}")
 
+          protocol_version = payment_info[:version] || X402.configuration.version
+          version_strategy = X402::Versions.for(protocol_version)
+
           facilitator_client = X402::FacilitatorClient.new
           settlement_result = facilitator_client.settle(
             payment_info[:payload],
-            payment_info[:requirement].to_h
+            payment_info[:requirement].to_h(version: protocol_version)
           )
 
           if settlement_result.success?
-            # Add settlement response header
-            response.headers["X-PAYMENT-RESPONSE"] = settlement_result.to_base64
+            response.headers[version_strategy.response_header_name] = settlement_result.to_base64
             ::Rails.logger.info("x402 settlement successful: #{settlement_result.transaction}")
           else
-            # Settlement failed - in optimistic mode, user already got the service
-            # In non-optimistic mode, this will be caught before the response is sent
             ::Rails.logger.error("x402 settlement failed: #{settlement_result.error_reason}")
           end
 
@@ -164,92 +268,6 @@ module X402
         end
       end
 
-      def browser_request?
-        # If Accept header explicitly requests JSON, return JSON even from browsers
-        accept_header = request.headers["Accept"].to_s
-        return false if accept_header.include?("application/json")
-
-        # Otherwise, check User-Agent for browser indicators
-        user_agent = request.headers["User-Agent"].to_s
-        user_agent.match?(/(Mozilla|Chrome|Safari|Firefox|Edge|Opera)/i)
-      end
-
-      def render_html_paywall(requirement_response)
-        html = <<~HTML
-          <!DOCTYPE html>
-          <html>
-          <head>
-            <title>Payment Required</title>
-            <style>
-              body {
-                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-                display: flex;
-                justify-content: center;
-                align-items: center;
-                min-height: 100vh;
-                margin: 0;
-                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-              }
-              .paywall-container {
-                background: white;
-                padding: 3rem;
-                border-radius: 1rem;
-                box-shadow: 0 20px 60px rgba(0,0,0,0.3);
-                max-width: 500px;
-                text-align: center;
-              }
-              h1 {
-                color: #333;
-                margin-bottom: 1rem;
-                font-size: 2rem;
-              }
-              p {
-                color: #666;
-                line-height: 1.6;
-                margin-bottom: 2rem;
-              }
-              .amount {
-                font-size: 2.5rem;
-                font-weight: bold;
-                color: #667eea;
-                margin: 1.5rem 0;
-              }
-              .info {
-                background: #f7f7f7;
-                padding: 1rem;
-                border-radius: 0.5rem;
-                margin: 1.5rem 0;
-                font-size: 0.9rem;
-              }
-              code {
-                background: #e0e0e0;
-                padding: 0.2rem 0.5rem;
-                border-radius: 0.25rem;
-                font-family: monospace;
-              }
-            </style>
-          </head>
-          <body>
-            <div class="paywall-container">
-              <h1>💳 Payment Required</h1>
-              <p>This resource requires payment to access.</p>
-              <div class="amount">$#{format('%.3f', requirement_response[:accepts].first[:maxAmountRequired].to_i / 1_000_000.0)}</div>
-              <div class="info">
-                <p><strong>Network:</strong> #{requirement_response[:accepts].first[:network]}</p>
-                <p><strong>Asset:</strong> USDC</p>
-                <p><strong>Resource:</strong> #{requirement_response[:accepts].first[:resource]}</p>
-              </div>
-              <p style="font-size: 0.85rem; color: #999;">
-                This resource uses the x402 payment protocol.
-                API clients can make payments programmatically by including the X-PAYMENT header.
-              </p>
-            </div>
-          </body>
-          </html>
-        HTML
-
-        render html: html.html_safe, status: :payment_required
-      end
     end
   end
 end

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

@@ -8,9 +8,9 @@ X402.configure do |config|
   # Set this via environment variable: X402_WALLET_ADDRESS
   config.wallet_address = ENV.fetch("X402_WALLET_ADDRESS", nil)
 
-  # Facilitator URL (default: https://x402.org/facilitator)
+  # Facilitator URL (default: https://www.x402.org/facilitator)
   # The facilitator handles payment verification and settlement
-  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://x402.org/facilitator")
+  config.facilitator = ENV.fetch("X402_FACILITATOR_URL", "https://www.x402.org/facilitator")
 
   # Blockchain network to use
   # Options: "base-sepolia" (testnet), "base" (mainnet), "avalanche-fuji" (testnet), "avalanche" (mainnet)
@@ -19,17 +19,6 @@ X402.configure do |config|
 
   # Currency symbol (currently only USDC is supported)
   config.currency = ENV.fetch("X402_CURRENCY", "USDC")
-
-  # Custom RPC URLs (optional)
-  # Use custom RPC endpoints from providers like QuickNode, Alchemy, or Infura
-  # for better reliability and rate limits. Uncomment and configure as needed:
-  #
-  # config.rpc_urls["base"] = "https://your-base-rpc.quiknode.pro/your-key"
-  # config.rpc_urls["base-sepolia"] = "https://your-sepolia-rpc.quiknode.pro/your-key"
-  # config.rpc_urls["avalanche"] = "https://your-avalanche-rpc.quiknode.pro/your-key"
-  #
-  # Or use environment variables (see README.md for details):
-  # X402_BASE_RPC_URL, X402_BASE_SEPOLIA_RPC_URL, etc.
 end
 
 # Validate configuration on initialization

data/lib/x402/rails/version.rb

@@ -2,6 +2,6 @@
 
 module X402
   module Rails
-    VERSION = "0.2.1"
+    VERSION = "1.0.0"
   end
 end