x402-rails 0.2.0 → 1.0.0

data/lib/x402/rails.rb

@@ -9,6 +9,7 @@ require "base64"
 require_relative "rails/version"
 require_relative "../x402/configuration"
 require_relative "../x402/chains"
+require_relative "../x402/versions"
 require_relative "../x402/payment_requirement"
 require_relative "../x402/payment_payload"
 require_relative "../x402/settlement_response"

data/lib/x402/requirement_generator.rb

@@ -2,54 +2,97 @@
 
 module X402
   class RequirementGenerator
-    def self.generate(amount:, resource:, description: nil, chain: nil, currency: nil)
+    def self.generate(amount:, resource:, description: nil, chain: nil, currency: nil,
+                      wallet_address: nil, fee_payer: nil, version: nil, accepts: nil)
       config = X402.configuration
-      chain_name = chain || config.chain
+      protocol_version = version || config.version
+      version_strategy = X402::Versions.for(protocol_version)
 
-      # Get chain and currency configuration for this specific chain
-      chain_config = X402.chain_config(chain_name)
-      currency_config = X402.currency_config_for_chain(chain_name)
+      accepted_payments = resolve_accepted_payments(
+        accepts: accepts,
+        chain: chain,
+        currency: currency
+      )
 
-      # Convert amount to atomic units
-      atomic_amount = convert_to_atomic(amount, currency_config[:decimals])
+      formatted_accepts = accepted_payments.map do |payment|
+        build_formatted_requirement(
+          amount: amount,
+          resource: resource,
+          description: description,
+          chain: payment[:chain],
+          currency: payment[:currency],
+          wallet_address: wallet_address || payment[:wallet_address] || config.wallet_address,
+          fee_payer: fee_payer,
+          version_strategy: version_strategy
+        )
+      end
 
-      # Get asset address (USDC contract address for the chain)
-      asset_address = X402.usdc_address_for(chain_name)
+      version_strategy.format_requirement_response(
+        accepts: formatted_accepts,
+        resource: {
+          url: resource,
+          description: description || "Payment required for #{resource}",
+          mime_type: "application/json"
+        },
+        error: "Payment required to access this resource"
+      )
+    end
 
-      # Build EIP-712 domain info (required for signature verification)
-      # IMPORTANT: The name must match what the USDC contract returns for name()
-      # Testnets use "USDC", mainnets use "USD Coin" or "USDC" depending on chain
-      eip712_domain = {
-        name: currency_config[:name],
-        version: currency_config[:version]
-      }
+    def self.build_formatted_requirement(amount:, resource:, description:, chain:, currency:,
+                                         wallet_address:, fee_payer:, version_strategy:)
+      token_config = X402.token_config_for(chain, currency)
+      asset_address = X402.asset_address_for(chain, currency)
+      atomic_amount = convert_to_atomic(amount, token_config[:decimals])
+      extra_data = build_extra_data(chain, token_config, fee_payer)
 
-      # Create payment requirement
-      requirement = PaymentRequirement.new(
+      internal_requirement = {
         scheme: "exact",
-        network: chain_name,
-        max_amount_required: atomic_amount,
+        network: chain,
+        amount: atomic_amount,
         asset: asset_address,
-        pay_to: config.wallet_address,
+        pay_to: wallet_address,
         resource: resource,
         description: description || "Payment required for #{resource}",
         max_timeout_seconds: 600,
         mime_type: "application/json",
-        extra: eip712_domain
-      )
-
-      # Build full response
-      {
-        x402Version: 1,
-        error: "Payment required to access this resource",
-        accepts: [requirement.to_h]
+        extra: extra_data
       }
+
+      version_strategy.format_requirement(internal_requirement)
+    end
+
+    def self.resolve_accepted_payments(accepts:, chain:, currency:)
+      config = X402.configuration
+
+      if accepts && !accepts.empty?
+        accepts.map do |acc|
+          {
+            chain: acc[:chain],
+            currency: acc[:currency] || "USDC",
+            wallet_address: acc[:wallet_address]
+          }
+        end
+      elsif chain
+        [{ chain: chain, currency: currency || config.currency, wallet_address: nil }]
+      else
+        config.effective_accepted_payments
+      end
     end
 
     def self.convert_to_atomic(amount, decimals)
-      # Convert USD amount to atomic units
-      # For USDC with 6 decimals: $0.001 = 1000 atomic units
       (amount.to_f * (10**decimals)).to_i
     end
+
+    def self.build_extra_data(chain_name, token_config, fee_payer_override)
+      if X402.solana_chain?(chain_name)
+        fee_payer = fee_payer_override || X402.fee_payer_for(chain_name)
+        { feePayer: fee_payer }
+      else
+        {
+          name: token_config[:name],
+          version: token_config[:version]
+        }
+      end
+    end
   end
 end

data/lib/x402/versions/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module X402
+  module Versions
+    class Base
+      def version_number
+        raise NotImplementedError
+      end
+
+      def payment_header_name
+        raise NotImplementedError
+      end
+
+      def response_header_name
+        raise NotImplementedError
+      end
+
+      def requirement_header_name
+        raise NotImplementedError
+      end
+
+      def format_network(internal_network)
+        raise NotImplementedError
+      end
+
+      def parse_network(network)
+        raise NotImplementedError
+      end
+
+      def format_requirement(requirement)
+        raise NotImplementedError
+      end
+
+      def format_requirement_response(accepts:, resource:, error:)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/x402/versions/v1.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module X402
+  module Versions
+    class V1 < Base
+      def version_number
+        1
+      end
+
+      def payment_header_name
+        "X-PAYMENT"
+      end
+
+      def response_header_name
+        "X-PAYMENT-RESPONSE"
+      end
+
+      def requirement_header_name
+        nil
+      end
+
+      def format_network(internal_network)
+        internal_network
+      end
+
+      def parse_network(network)
+        network
+      end
+
+      def format_requirement(requirement)
+        {
+          scheme: requirement[:scheme],
+          network: format_network(requirement[:network]),
+          maxAmountRequired: requirement[:amount].to_s,
+          asset: requirement[:asset],
+          payTo: requirement[:pay_to],
+          resource: requirement[:resource],
+          description: requirement[:description],
+          maxTimeoutSeconds: requirement[:max_timeout_seconds],
+          mimeType: requirement[:mime_type],
+          extra: requirement[:extra]
+        }.compact
+      end
+
+      def format_requirement_response(accepts:, resource:, error:)
+        {
+          x402Version: 1,
+          error: error,
+          accepts: accepts
+        }
+      end
+    end
+  end
+end

data/lib/x402/versions/v2.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module X402
+  module Versions
+    class V2 < Base
+      def version_number
+        2
+      end
+
+      def payment_header_name
+        "PAYMENT-SIGNATURE"
+      end
+
+      def response_header_name
+        "PAYMENT-RESPONSE"
+      end
+
+      def requirement_header_name
+        "PAYMENT-REQUIRED"
+      end
+
+      def format_network(internal_network)
+        X402.to_caip2(internal_network)
+      end
+
+      def parse_network(network)
+        if network.include?(":")
+          X402.from_caip2(network)
+        else
+          network
+        end
+      end
+
+      def format_requirement(requirement)
+        {
+          scheme: requirement[:scheme],
+          network: format_network(requirement[:network]),
+          amount: requirement[:amount].to_s,
+          asset: requirement[:asset],
+          payTo: requirement[:pay_to],
+          maxTimeoutSeconds: requirement[:max_timeout_seconds],
+          extra: requirement[:extra]
+        }.compact
+      end
+
+      def format_requirement_response(accepts:, resource:, error:)
+        {
+          x402Version: 2,
+          error: error,
+          resource: {
+            url: resource[:url],
+            description: resource[:description],
+            mimeType: resource[:mime_type]
+          }.compact,
+          accepts: accepts,
+          extensions: {}
+        }
+      end
+    end
+  end
+end

data/lib/x402/versions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "versions/base"
+require_relative "versions/v1"
+require_relative "versions/v2"
+
+module X402
+  module Versions
+    def self.for(version)
+      case version.to_i
+      when 1 then V1.new
+      when 2 then V2.new
+      else raise ConfigurationError, "Unsupported x402 version: #{version}"
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: x402-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - QuickNode
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-30 00:00:00.000000000 Z
+date: 2026-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -128,9 +128,11 @@ email:
 - zach+x402@quiknode.io
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
 files:
 - ".rspec"
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -149,12 +151,17 @@ files:
 - lib/x402/rails/version.rb
 - lib/x402/requirement_generator.rb
 - lib/x402/settlement_response.rb
+- lib/x402/versions.rb
+- lib/x402/versions/base.rb
+- lib/x402/versions/v1.rb
+- lib/x402/versions/v2.rb
 homepage: https://github.com/quiknode-labs/x402-rails
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/quiknode-labs/x402-rails
   source_code_uri: https://github.com/quiknode-labs/x402-rails
+  documentation_uri: https://github.com/quiknode-labs/x402-rails#readme
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -173,5 +180,5 @@ requirements: []
 rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
-summary: Rails integration for x402 payment protocol
+summary: Rails integration for x402 payment protocol (supporting x402 v2).
 test_files: []