mpp-rb 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71efa5e58021d08e4ed10c0156ed9b140923b0f3ebeb5ce6b42839594c27dd6
-  data.tar.gz: d40e3c4994086eea6f2c11023f47fda635637ae6815dc263d63c12ca10235ae8
+  metadata.gz: c38b87554f2c1cbef8acfb7d2ba2197b14140500e52bff79276602c76051f8ed
+  data.tar.gz: c11b04aef7e116a9b298e3b4b4286dfc4194348b6bd2aca60b1d3f235911ac25
 SHA512:
-  metadata.gz: af6ba306f236fb01dd140f63ce51c764fdee655a7f1282d7adad87d8586e4838d43f096ca79a4053dbab703afdc6fa1806d3e20ea6b6afa75c7c70bf6d3885f3
-  data.tar.gz: db9bc204d61dcdb4c3e9d0b8f9034f935dd38d4291b71b37e61a29889240b27667400e5c48333d2cf39e2d6513b5af70368a354a8a20fd5a543558b07b68f700
+  metadata.gz: 795895e5b9b8a768d96468c7f34b468b9a205e694c2b212dc1fca00ecfd2e5906c95ec95455ac79432f1ba95b21a91ba31cd71ccecbb1dbc1226a3cf274ccbf8
+  data.tar.gz: 81855362a29e248846445b3cebb0a1bce2a4f2cc2164c49e462ac923ade2fc1d30ef527786579313ffe270d02c89ec8b32a0dd0c09a74403bc69820de112ee10

data/README.md

@@ -49,6 +49,61 @@ else
 end
 ```
 
+### Multiple methods
+
+```ruby
+server = Mpp.create(methods: [tempo, evm, stripe])
+
+paid = server.compose(
+  [tempo, {amount: "0.01"}],
+  [evm, {amount: "0.01"}],
+  [stripe, {amount: "0.01", currency: "usd"}]
+)
+
+result = paid.call(
+  authorization: env["HTTP_AUTHORIZATION"],
+  payment_signature: env["HTTP_PAYMENT_SIGNATURE"],
+  accept_payment: env["HTTP_ACCEPT_PAYMENT"],
+  url: request.url,
+  http_method: request.request_method
+)
+
+if result.payment_required?
+  resp = result.to_response
+else
+  credential, receipt = result.payment
+end
+```
+
+`evm.charge` additionally emits `PAYMENT-REQUIRED` and accepts `PAYMENT-SIGNATURE` (x402 v2 exact) when a facilitator is configured:
+
+```ruby
+# Public / testnet facilitator
+x402: {facilitator: "https://x402.org/facilitator"}
+
+# Per-request headers (bearer token, CDP JWT, etc.)
+x402: {facilitator: {url: facilitator_url, headers: -> { {"Authorization" => "Bearer #{token}"} }}}
+
+# The proc may take the request path (`/verify`, `/settle`) when headers differ per call
+x402: {facilitator: {url: cdp_url, headers: ->(path) { cdp_headers(path) }}}
+
+# Any client with #verify / #settle
+x402: {facilitator: cdp_client}
+```
+
+Tempo charge can sponsor gas through a hosted fee payer, or skip local RPC by sending credentials to a Tempo API-compatible relay. Both use the same `{url:, headers:}` shape as the x402 facilitator:
+
+```ruby
+# Hosted fee payer (JSON-RPC eth_signRawTransaction)
+fee_payer: {url: sponsor_url, headers: -> { {"Authorization" => "Bearer #{token}"} }}
+
+# Local co-sign
+fee_payer: Mpp::Methods::Tempo::Account.from_key(ENV.fetch("FEE_PAYER_KEY"))
+
+# Relay (POST /v1/mpp/validate then /v1/mpp/broadcast)
+relay: {url: "https://api.tempo.xyz", headers: -> { {"tempo-api-key" => ENV.fetch("TEMPO_API_KEY")} }}
+```
+
 ### Client
 
 ```ruby
@@ -122,6 +177,10 @@ env["mpp.charge"] = { amount: "0.50", description: "Paid endpoint" }
 |---------|-------------|
 | [tempo_charge](./examples/tempo_charge/) | Tempo testnet payments via Sinatra |
 | [stripe_charge](./examples/stripe_charge/) | Stripe payments via Shared Payment Tokens |
+| [compose](./examples/compose/) | Tempo + Base USDC + Stripe SPTs on one endpoint |
+| [evm_x402](./examples/evm_x402/) | EVM charge with x402 exact compatibility |
+| [tempo_feepayer](./examples/tempo_feepayer/) | Tempo charge with a hosted fee-payer `{url:, headers:}` |
+| [tempo_relay](./examples/tempo_relay/) | Tempo charge delegated to an MPP relay `{url:, headers:}` |
 
 Each example is a standalone Sinatra app with `/free` and `/paid` endpoints. To run one:
 
@@ -143,8 +202,11 @@ npx mppx http://localhost:4567/paid
 |--------|---------------|---------------|
 | Tempo | Yes | Yes |
 | Stripe | Yes | Yes |
+| EVM (`evm.charge`, x402 exact) | No | Yes |
+
+Tempo charge transaction construction is implemented directly in Ruby. Runtime dependency: `keccak` (Tempo attribution memos). Optional dependencies: `eth` (account signing, EIP-3009 recovery) and `rlp` (fee payer envelope).
 
-Tempo charge transaction construction is implemented directly in Ruby. Optional dependencies: `eth` (account signing) and `rlp` (fee payer envelope).
+`Mpp.create` accepts a single `method:` (unchanged) or `methods:` to register several payment methods. `server.compose` presents every method as multiple `WWW-Authenticate` challenges; `evm.charge` also emits `PAYMENT-REQUIRED` and accepts `PAYMENT-SIGNATURE` when a facilitator is configured. The Ruby HTTP client does not yet sign EVM or x402 credentials.
 
 ## Protocol
 

data/lib/mpp/errors.rb

@@ -30,6 +30,7 @@ module Mpp
       end
       subclass.instance_variable_set(:@title, to_title(name)) unless subclass.instance_variable_defined?(:@title)
       subclass.instance_variable_set(:@status, 402) unless subclass.instance_variable_defined?(:@status)
+      subclass.instance_variable_set(:@hint, nil) unless subclass.instance_variable_defined?(:@hint)
     end
 
     class << self
@@ -44,6 +45,9 @@ module Mpp
       sig { returns(T.nilable(String)) }
       attr_reader :title
 
+      sig { returns(T.nilable(String)) }
+      attr_reader :hint
+
       private
 
       sig { params(name: String).returns(String) }
@@ -60,6 +64,7 @@ module Mpp
     @status = T.let(402, Integer)
     @type = T.let("#{BASE_URI}/payment-error", String)
     @title = T.let("Payment Error", String)
+    @hint = T.let(nil, T.nilable(String))
 
     sig { returns(T.untyped) }
     def status = self.class.status
@@ -67,6 +72,8 @@ module Mpp
     def type = self.class.type
     sig { returns(T.untyped) }
     def title = self.class.title
+    sig { returns(T.untyped) }
+    def hint = self.class.hint
 
     # Convert to RFC 9457 Problem Details format.
     sig { params(challenge_id: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
@@ -77,14 +84,26 @@ module Mpp
         "status" => status,
         "detail" => message
       }
+      details["hint"] = hint if hint
       details["challengeId"] = challenge_id if challenge_id
       details
     end
   end
 
+  # Default hint messages for payment errors.
+  module Hints
+    PAYMENT_REQUIRED = "Use a supported wallet to pay for this resource using one of the supported " \
+      "payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md"
+    MALFORMED_CREDENTIAL = "Use a supported wallet to construct valid credentials for one of the supported " \
+      "payment methods returned in the WWW-Authenticate header. See https://mpp.dev/tools/wallet.md"
+    METHOD_UNSUPPORTED = PAYMENT_REQUIRED
+  end
+
   class PaymentRequiredError < PaymentError
     extend T::Sig
 
+    @hint = T.let(Hints::PAYMENT_REQUIRED, T.nilable(String))
+
     sig { params(realm: T.untyped, description: T.untyped).void }
     def initialize(realm: nil, description: nil)
       parts = ["Payment is required"]
@@ -97,6 +116,8 @@ module Mpp
   class MalformedCredentialError < PaymentError
     extend T::Sig
 
+    @hint = T.let(Hints::MALFORMED_CREDENTIAL, T.nilable(String))
+
     sig { params(reason: T.untyped).void }
     def initialize(reason: nil)
       msg = reason ? "Credential is malformed: #{reason}." : "Credential is malformed."
@@ -173,6 +194,7 @@ module Mpp
     @status = T.let(400, Integer)
     @type = T.let("#{BASE_URI}/method-unsupported", String)
     @title = T.let("Method Unsupported", String)
+    @hint = T.let(Hints::METHOD_UNSUPPORTED, T.nilable(String))
 
     sig { params(method: T.untyped).void }
     def initialize(method: nil)

data/lib/mpp/http/headers.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Http
+    # Shared `{url:, headers:}` helpers used by the x402 facilitator and Tempo
+    # fee-payer and relay HTTP clients.
+    #
+    # `headers` may be:
+    #   * a Hash of static header names/values
+    #   * a zero-arity proc returning that Hash
+    #   * a proc receiving the request path (or JSON-RPC method) and returning
+    #     that Hash
+    #   * a nested Hash keyed by operation (`"verify"`, `"broadcast"`, …)
+    module Headers
+      extend T::Sig
+
+      module_function
+
+      sig { params(url: T.untyped).returns(String) }
+      def normalize_base_url(url)
+        base = url.to_s
+        base = base.chomp("/") while base.end_with?("/")
+        base
+      end
+
+      sig { params(config: T::Hash[T.untyped, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
+      def symbolize(config)
+        config.each_with_object({}) do |(key, value), acc|
+          acc[key.to_sym] = value
+        end
+      end
+
+      sig { params(headers: T.nilable(T::Hash[T.untyped, T.untyped])).returns(T::Hash[String, String]) }
+      def stringify(headers)
+        return {} if headers.nil?
+
+        headers.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s] = value.to_s
+        end
+      end
+
+      sig { params(source: T.untyped, path: String).returns(T::Hash[String, String]) }
+      def resolve(source, path)
+        return {} if source.nil?
+
+        if source.respond_to?(:call)
+          arity = source.respond_to?(:arity) ? source.arity : 1
+          source = (arity == 0) ? source.call : source.call(path)
+        end
+        return {} unless source.is_a?(Hash)
+
+        operation = path.to_s.delete_prefix("/")
+        last = T.let(operation.split("/").last, T.nilable(String))
+        keyed = source[operation] || source[operation.to_sym]
+        keyed ||= source[last] || source[last.to_sym] if last && last != operation
+        stringify(keyed.is_a?(Hash) ? keyed : source)
+      end
+    end
+  end
+end

data/lib/mpp/http.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Mpp
+  module Http
+    autoload :Headers, "mpp/http/headers"
+  end
+end

data/lib/mpp/methods/evm/assets.rb

@@ -0,0 +1,103 @@
+# typed: true
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Evm
+      # Known EIP-3009 assets plus helpers to resolve a currency config.
+      module Assets
+        Asset = Struct.new(:address, :decimals, :chain_id, :name, :version, keyword_init: true) do
+          def network
+            "eip155:#{chain_id}"
+          end
+        end
+
+        def self.hex_address(*chunks)
+          "0x#{chunks.join}"
+        end
+
+        BASE_USDC = Asset.new(
+          address: hex_address("833589fCD6eDb6E08f", "4c7C32D4f71b54bdA02913"),
+          decimals: 6,
+          chain_id: 8453,
+          name: "USD Coin",
+          version: "2"
+        )
+        BASE_SEPOLIA_USDC = Asset.new(
+          address: hex_address("036CbD53842c542663", "4e7929541eC2318f3dCF7e"),
+          decimals: 6,
+          chain_id: 84532,
+          name: "USDC",
+          version: "2"
+        )
+        CELO_USDC = Asset.new(
+          address: hex_address("cebA9300f2b948710d", "2653dD7B07f33A8B32118C"),
+          decimals: 6,
+          chain_id: 42220,
+          name: "USDC",
+          version: "2"
+        )
+        CELO_USDT = Asset.new(
+          address: hex_address("48065fbBE25f71C928", "2ddf5e1cD6D6A887483D5e"),
+          decimals: 6,
+          chain_id: 42220,
+          name: "Tether USD",
+          version: "1"
+        )
+        CELO_SEPOLIA_USDC = Asset.new(
+          address: hex_address("01C5C0122039549AD1", "493B8220cABEdD739BC44E"),
+          decimals: 6,
+          chain_id: 11142220,
+          name: "USDC",
+          version: "2"
+        )
+
+        private_class_method :hex_address
+
+        module_function
+
+        def resolve(currency, authorization: nil, chain_id: nil, decimals: nil)
+          if currency.is_a?(Asset)
+            auth = authorization_hash(authorization) || {"name" => currency.name, "version" => currency.version}
+            return {
+              address: checksum(currency.address),
+              chain_id: chain_id || currency.chain_id,
+              decimals: decimals || currency.decimals,
+              authorization: auth
+            }
+          end
+
+          address = currency.to_s
+          Kernel.raise ArgumentError, "EVM currency must be a known asset or 0x-prefixed address" unless address.match?(/\A0x[a-fA-F0-9]{40}\z/)
+          Kernel.raise ArgumentError, "EVM authorization requires `chain_id`." if chain_id.nil?
+          Kernel.raise ArgumentError, "EVM authorization requires `decimals`." if decimals.nil?
+
+          auth = authorization_hash(authorization)
+          Kernel.raise ArgumentError, "EVM authorization requires `authorization` metadata." unless auth
+
+          {
+            address: checksum(address),
+            chain_id: Kernel.Integer(chain_id),
+            decimals: Kernel.Integer(decimals),
+            authorization: auth
+          }
+        end
+
+        def checksum(address)
+          Authorization.checksum_address(address)
+        end
+
+        def authorization_hash(authorization)
+          return nil if authorization.nil?
+
+          name = authorization[:name] || authorization["name"]
+          version = authorization[:version] || authorization["version"]
+          Kernel.raise ArgumentError, "authorization requires name and version" if name.to_s.empty? || version.to_s.empty?
+
+          {"name" => name.to_s, "version" => version.to_s}
+        end
+        private_class_method :authorization_hash
+      end
+    end
+  end
+end

data/lib/mpp/methods/evm/authorization.rb

@@ -0,0 +1,140 @@
+# typed: false
+# frozen_string_literal: true
+
+module Mpp
+  module Methods
+    module Evm
+      # EIP-712 TransferWithAuthorization hashing and recovery.
+      module Authorization
+        DOMAIN_TYPE_HASH = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+        TRANSFER_TYPE_HASH = "TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+
+        module_function
+
+        def keccak256(data)
+          Kernel.require "eth"
+          Eth::Util.keccak256(data)
+        rescue Gem::LoadError
+          raise LoadError, "eth gem is not available"
+        end
+
+        def challenge_hash(challenge)
+          digest = keccak256("#{challenge.id}#{challenge.realm}")
+          "0x#{digest.unpack1("H*")}"
+        end
+
+        def checksum_address(address)
+          raw = address.to_s
+          hex = raw.delete_prefix("0x")
+          raise ArgumentError, "invalid address: #{address}" unless hex.match?(/\A[a-fA-F0-9]{40}\z/)
+
+          begin
+            hash = keccak256(hex.downcase).unpack1("H*")
+          rescue LoadError
+            return raw.start_with?("0x") ? raw : "0x#{hex}"
+          end
+
+          checksummed = hex.downcase.chars.each_with_index.map { |char, index|
+            (char.match?(/[a-f]/) && hash[index].to_i(16) >= 8) ? char.upcase : char
+          }.join
+          "0x#{checksummed}"
+        end
+
+        def signing_hash(authorization:, chain_id:, currency:, from:, to:, value:, valid_after:, valid_before:, nonce:)
+          domain = domain_separator(
+            name: authorization["name"] || authorization[:name],
+            version: authorization["version"] || authorization[:version],
+            chain_id: chain_id,
+            verifying_contract: currency
+          )
+          struct = struct_hash(
+            from: from,
+            to: to,
+            value: value,
+            valid_after: valid_after,
+            valid_before: valid_before,
+            nonce: nonce
+          )
+          keccak256("\x19\x01".b + domain + struct)
+        end
+
+        def recover(authorization:, chain_id:, currency:, payload:)
+          hash = signing_hash(
+            authorization: authorization,
+            chain_id: chain_id,
+            currency: currency,
+            from: payload["from"],
+            to: payload["to"],
+            value: payload["value"],
+            valid_after: payload["validAfter"],
+            valid_before: payload["validBefore"],
+            nonce: payload["nonce"]
+          )
+          recover_address(hash, payload["signature"])
+        end
+
+        def domain_separator(name:, version:, chain_id:, verifying_contract:)
+          keccak256(
+            abi_encode(
+              keccak256(DOMAIN_TYPE_HASH),
+              keccak256(name),
+              keccak256(version),
+              uint256(chain_id),
+              address_word(verifying_contract)
+            )
+          )
+        end
+
+        def struct_hash(from:, to:, value:, valid_after:, valid_before:, nonce:)
+          keccak256(
+            abi_encode(
+              keccak256(TRANSFER_TYPE_HASH),
+              address_word(from),
+              address_word(to),
+              uint256(value),
+              uint256(valid_after),
+              uint256(valid_before),
+              bytes32_word(nonce)
+            )
+          )
+        end
+
+        def abi_encode(*values)
+          values.join
+        end
+
+        def uint256(value)
+          value = Integer(value)
+          raise ArgumentError, "uint256 out of range" if value.negative? || value >= (1 << 256)
+
+          [value.to_s(16).rjust(64, "0")].pack("H*")
+        end
+
+        def address_word(value)
+          hex = value.to_s.delete_prefix("0x")
+          raise ArgumentError, "invalid address: #{value}" unless hex.match?(/\A[a-fA-F0-9]{40}\z/)
+
+          [hex].pack("H*").rjust(32, "\x00".b)
+        end
+
+        def bytes32_word(value)
+          hex = value.to_s.delete_prefix("0x")
+          raise ArgumentError, "invalid bytes32: #{value}" unless hex.match?(/\A[a-fA-F0-9]{64}\z/)
+
+          [hex].pack("H*")
+        end
+
+        def recover_address(hash, signature)
+          Kernel.require "eth"
+
+          sig = signature.to_s
+          sig = "0x#{sig}" unless sig.start_with?("0x")
+          recovered_key = Eth::Signature.recover(hash, sig)
+          Eth::Util.public_key_to_address(recovered_key).to_s
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/mpp/methods/evm/charge_intent.rb

@@ -0,0 +1,129 @@
+# typed: false
+# frozen_string_literal: true
+
+require "time"
+
+module Mpp
+  module Methods
+    module Evm
+      # Server-side EVM charge intent: recover EIP-3009, then settle via facilitator.
+      class ChargeIntent
+        attr_reader :name, :facilitator, :authorization, :max_timeout_seconds, :route_binding
+
+        def initialize(authorization:, facilitator:, max_timeout_seconds: 300, route_binding: :resource)
+          @name = "charge"
+          @authorization = authorization
+          @facilitator = facilitator
+          @max_timeout_seconds = max_timeout_seconds
+          @route_binding = route_binding
+        end
+
+        def verify(credential, request)
+          payload = credential.payload
+          unless payload.is_a?(Hash) && payload["type"] == "authorization"
+            raise Mpp::VerificationError, "EVM authorization credentials are not supported for this challenge"
+          end
+
+          if request.dig("methodDetails", "splits")
+            raise Mpp::VerificationFailedError.new(reason: "EVM authorization credentials do not support splits")
+          end
+
+          unless addresses_equal?(payload["to"], request["recipient"])
+            raise Mpp::VerificationFailedError.new(reason: "EVM authorization recipient mismatch")
+          end
+          unless payload["value"].to_s == request["amount"].to_s
+            raise Mpp::VerificationFailedError.new(reason: "EVM authorization amount mismatch")
+          end
+
+          unless x402_credential?(credential)
+            expected_nonce = Authorization.challenge_hash(credential.challenge)
+            unless payload["nonce"].to_s.downcase == expected_nonce.downcase
+              raise Mpp::VerificationFailedError.new(reason: "EVM authorization challenge hash mismatch")
+            end
+          end
+
+          now = Time.now.to_i
+          raise Mpp::VerificationFailedError.new(reason: "EVM authorization is not valid yet") if Integer(payload["validAfter"]) > now
+          raise Mpp::VerificationFailedError.new(reason: "EVM authorization has expired") if Integer(payload["validBefore"]) <= now
+
+          chain_id = request.dig("methodDetails", "chainId")
+          raise Mpp::VerificationFailedError.new(reason: "EVM authorization requires chainId") if chain_id.nil?
+
+          signer = Authorization.recover(
+            authorization: @authorization,
+            chain_id: chain_id,
+            currency: request["currency"],
+            payload: payload
+          )
+          unless signer && addresses_equal?(signer, payload["from"])
+            raise Mpp::VerificationFailedError.new(reason: "EVM authorization signature mismatch")
+          end
+
+          checksummed_from = Authorization.checksum_address(payload["from"])
+          source = "did:pkh:eip155:#{chain_id}:#{checksummed_from}"
+          if credential.source && credential.source != source
+            raise Mpp::VerificationFailedError.new(reason: "EVM authorization source mismatch")
+          end
+
+          settled = settle(payload, request)
+          Mpp::Receipt.success(settled.fetch("transaction"), method: "evm")
+        end
+
+        def payment_requirements(request)
+          Mpp::X402::Server.to_payment_requirements(
+            request,
+            authorization: @authorization,
+            max_timeout_seconds: @max_timeout_seconds
+          )
+        end
+
+        private
+
+        def settle(payload, request)
+          requirements = payment_requirements(request)
+          payment_payload = {
+            "accepted" => requirements,
+            "payload" => {
+              "authorization" => {
+                "from" => payload["from"],
+                "nonce" => payload["nonce"],
+                "to" => payload["to"],
+                "validAfter" => payload["validAfter"].to_s,
+                "validBefore" => payload["validBefore"].to_s,
+                "value" => payload["value"].to_s
+              },
+              "signature" => payload["signature"]
+            },
+            "x402Version" => Mpp::X402::VERSION
+          }
+
+          verified = @facilitator.verify(payment_payload, requirements)
+          unless verified["isValid"]
+            raise Mpp::VerificationFailedError.new(
+              reason: verified["invalidMessage"] || verified["invalidReason"] || "EVM facilitator verify failed"
+            )
+          end
+
+          settled = @facilitator.settle(payment_payload, requirements)
+          unless settled["success"]
+            raise Mpp::VerificationFailedError.new(
+              reason: settled["errorMessage"] || settled["errorReason"] || "EVM facilitator settlement failed"
+            )
+          end
+
+          settled
+        end
+
+        def x402_credential?(credential)
+          credential.payload.is_a?(Hash) && credential.payload["_x402"] == true
+        end
+
+        def addresses_equal?(left, right)
+          return false if left.nil? || right.nil?
+
+          left.to_s.delete_prefix("0x").downcase == right.to_s.delete_prefix("0x").downcase
+        end
+      end
+    end
+  end
+end