rail0-sdk 1.0.0

data/lib/rail0/resources/webhooks.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Webhook subscription management (requires JWT).
+    #
+    # A subscription covers a SET of topics — one shared secret and one circuit breaker
+    # for all of them — and each delivery names the event that fired in `X-Rail0-Topic`.
+    # Two subscriptions for the same callback_url must not overlap: one event delivered
+    # twice under two different secrets is indistinguishable from a duplicate at the
+    # receiving end, so the gateway answers 409 and names the topic that collided.
+    # See {TOPICS} for the accepted values.
+    class Webhooks
+      include Query
+
+      # Event topics a subscription can carry. It may carry any non-empty subset.
+      TOPICS = %w[
+        payments.created
+        payments.signed
+        payments.authorized
+        payments.charged
+        payments.captured
+        payments.voided
+        payments.released
+        payments.refunded
+        payments.expired
+        payments.failed
+        payments.disputed
+        payments.dispute_closed
+      ].freeze
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List the account's webhooks.
+      # @param topic [String, nil] Narrow to subscriptions that INCLUDE this event
+      #   (see {TOPICS}). Singular on purpose: the question is which subscriptions
+      #   deliver one event, whatever else they also deliver.
+      # @param active [Boolean, nil] Filter by active flag.
+      # @param circuit_state [String, nil] Filter by circuit state ("closed" or "open").
+      # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
+      # @param page [Integer, nil] Page number (1-based).
+      # @param per_page [Integer, nil] Items per page (max 100).
+      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+      def list(topic: nil, active: nil, circuit_state: nil, sort: nil, page: nil, per_page: nil)
+        query = build_query(topic: topic, active: active, circuit_state: circuit_state,
+                            sort: sort, page: page, per_page: per_page)
+        http.get_list("/webhooks#{query}")
+      end
+
+      # Register a new webhook. The response includes the one-time shared_secret
+      # used to verify delivery signatures — it is shown only on create and rotate.
+      # @param name [String] Human-readable name.
+      # @param callback_url [String] HTTPS URL the gateway POSTs events to.
+      # @param topics [Array<String>] One or more of {TOPICS}. Repeats are collapsed by
+      #   the gateway; overlapping another subscription on the same callback_url is a 409
+      #   naming the topic that collided.
+      # @return [Hash] webhook record including shared_secret
+      def create(name:, callback_url:, topics:)
+        http.post("/webhooks", { name: name, callback_url: callback_url, topics: Array(topics) })
+      end
+
+      # Fetch a single webhook.
+      # @param id [String] Webhook UUID.
+      # @return [Hash]
+      def get(id)
+        http.get("/webhooks/#{id}")
+      end
+
+      # Update a webhook's name, callback_url, and/or topics.
+      # @param id [String] Webhook UUID.
+      # @param name [String, nil]
+      # @param callback_url [String, nil]
+      # @param topics [Array<String>, nil] REPLACES the whole set, which is also how a
+      #   topic is removed: send the union to add one, the remainder to drop one. The
+      #   shared secret is untouched.
+      # @return [Hash]
+      def update(id, name: nil, callback_url: nil, topics: nil)
+        body = {}
+        body[:name]         = name          unless name.nil?
+        body[:callback_url] = callback_url  unless callback_url.nil?
+        body[:topics]       = Array(topics) unless topics.nil?
+        http.patch("/webhooks/#{id}", body)
+      end
+
+      # Re-enable a disabled webhook.
+      # @param id [String] Webhook UUID.
+      # @return [Hash]
+      def enable(id)
+        http.put("/webhooks/#{id}/enable")
+      end
+
+      # Disable a webhook (stops deliveries without deleting it).
+      # @param id [String] Webhook UUID.
+      # @return [Hash]
+      def disable(id)
+        http.put("/webhooks/#{id}/disable")
+      end
+
+      # Generate a new shared secret, returned once on the response.
+      # @param id [String] Webhook UUID.
+      # @return [Hash] webhook record including the new shared_secret
+      def rotate_secret(id)
+        http.put("/webhooks/#{id}/rotate_secret")
+      end
+
+      # Reset the delivery circuit breaker and re-enable the webhook.
+      # @param id [String] Webhook UUID.
+      # @return [Hash]
+      def reset_circuit(id)
+        http.put("/webhooks/#{id}/reset_circuit")
+      end
+
+      # List delivery attempts for a webhook.
+      # @param id [String] Webhook UUID.
+      # @param status [String, nil] Filter by delivery status ("pending", "delivered", "failed").
+      # @param topic [String, nil] Filter by event topic.
+      # @param payment_id [String, nil] Filter by the payment the delivery is for.
+      # @param since [String, nil] Only deliveries at/after this ISO-8601 time.
+      # @param until_time [String, nil] Only deliveries at/before this ISO-8601 time (query key: "until").
+      # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
+      # @param page [Integer, nil] Page number (1-based).
+      # @param per_page [Integer, nil] Items per page (max 100).
+      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+      def event_callbacks(id, status: nil, topic: nil, payment_id: nil, since: nil,
+                          until_time: nil, sort: nil, page: nil, per_page: nil)
+        query = build_query(status: status, topic: topic, payment_id: payment_id, since: since,
+                            until: until_time, sort: sort, page: page, per_page: per_page)
+        http.get_list("/webhooks/#{id}/event_callbacks#{query}")
+      end
+
+      # Delete a webhook. Returns HTTP 204.
+      # @param id [String] Webhook UUID.
+      # @return [nil]
+      def delete(id)
+        http.delete("/webhooks/#{id}")
+      end
+    end
+  end
+end

data/lib/rail0/signing.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+require "json"
+
+begin
+  original_verbose = $VERBOSE
+  $VERBOSE = nil
+  require "eth"
+rescue LoadError => e
+  raise e,
+        "Rail0::Signing requires the 'eth' gem. Add `gem 'eth', '~> 0.5'` to your Gemfile."
+ensure
+  $VERBOSE = original_verbose
+end
+
+module Rail0
+  # EIP-712 and EIP-3009 signing utilities for RAIL0 payments.
+  #
+  # Requires the optional signing dependency:
+  #   gem 'eth', '~> 0.5'
+  #
+  # No private key is ever sent to the API — signatures are built off-chain
+  # and included in the request body.
+  #
+  # ## Typical usage (simplest path)
+  #
+  #   resp = client.payments.create(chain_id: 84532, mode: "authorize", amount: "100.00", token: "0x...", payer: "0x...", payee: "0x...")
+  #   sig  = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, resp[:signing_payload])
+  #   client.payments.sign(resp[:rail0_id], { signature: sig.to_hex })
+  #
+  module Signing
+    # EIP-712 domain of the ERC-20 token (NOT the RAIL0 contract).
+    TokenDomain = Struct.new(:name, :version, :chain_id, :verifying_contract, keyword_init: true)
+
+    # EIP-3009 transferWithAuthorization signature.
+    # Call {to_hex} to assemble the 65-byte hex string expected by `PUT /payments/{id}/sign`.
+    Eip3009Signature = Struct.new(:v, :r, :s, keyword_init: true) do
+      # Encodes the signature as a 0x-prefixed 65-byte hex string (r ++ s ++ v).
+      # This is the format expected by the `signature` field of PayerSignatureRequest.
+      #
+      # @return [String] "0x" + r (32 bytes) + s (32 bytes) + v (1 byte), 132 chars total.
+      def to_hex
+        raise ArgumentError, "r and s must be 0x-prefixed hex strings" unless r.start_with?("0x") && s.start_with?("0x")
+
+        "0x#{r[2..]}#{s[2..]}#{v.to_s(16).rjust(2, '0')}"
+      end
+    end
+
+    # Parameters for a raw transferWithAuthorization signature.
+    SignTransferParams = Struct.new(
+      :from, :to, :value, :valid_before, :nonce,
+      :valid_after,
+      keyword_init: true
+    ) do
+      def initialize(**)
+        super
+        self.valid_after ||= 0
+      end
+    end
+
+    # DEPRECATED — the parameter object of the removed {sign_authorize} /
+    # {sign_charge}. Kept only so existing code reaches those methods' migration
+    # message instead of a NameError while building their arguments; nothing in this
+    # SDK consumes it. Use {sign_payload} with the gateway's `signing_payload`.
+    SignPaymentParams = Struct.new(
+      :private_key, :payment, :nonce, :contract_address, :token_domain,
+      keyword_init: true
+    )
+
+    DOMAIN_TYPE   = "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+    TRANSFER_TYPE = "TransferWithAuthorization(address from,address to,uint256 value," \
+                    "uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+    RECEIVE_TYPE  = "ReceiveWithAuthorization(address from,address to,uint256 value," \
+                    "uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+
+    DOMAIN_TYPEHASH   = Eth::Util.keccak256(DOMAIN_TYPE)
+    TRANSFER_TYPEHASH = Eth::Util.keccak256(TRANSFER_TYPE)
+    RECEIVE_TYPEHASH  = Eth::Util.keccak256(RECEIVE_TYPE)
+
+    private_constant :DOMAIN_TYPE, :TRANSFER_TYPE, :RECEIVE_TYPE,
+                     :DOMAIN_TYPEHASH, :TRANSFER_TYPEHASH, :RECEIVE_TYPEHASH
+
+    # Primary types the gateway can ask us to sign. Which one a payment needs is
+    # the gateway's business: it builds its client per-payment with the deployment's
+    # contract_version, and the version selects the typehash, the domain and the
+    # field layout.
+    PRIMARY_TYPES = {
+      "TransferWithAuthorization" => TRANSFER_TYPEHASH,
+      "ReceiveWithAuthorization"  => RECEIVE_TYPEHASH
+    }.freeze
+    private_constant :PRIMARY_TYPES
+
+    # Resolve a payload's primaryType to its typehash, or refuse.
+    #
+    # NEVER guess. This used to be a ternary that fell back to the Transfer
+    # typehash for anything that wasn't the exact string "ReceiveWithAuthorization"
+    # — including a nil, a typo, or a primary type introduced by a newer gateway.
+    # The result is a perfectly well-formed signature over the WRONG digest: the
+    # call reports success, and the failure surfaces only on-chain, after gas,
+    # where it looks like a bad key. An unknown type means this SDK is older than
+    # the gateway it is talking to, which is a diagnosable condition. (#7)
+    def self.typehash_for(primary_type)
+      PRIMARY_TYPES.fetch(primary_type.to_s) do
+        raise ArgumentError,
+              "unsupported signing payload primaryType #{primary_type.inspect} " \
+              "(expected one of #{PRIMARY_TYPES.keys.join(', ')}) — this SDK is older " \
+              "than the gateway it is talking to; upgrade rail0-ruby"
+      end
+    end
+
+    # Accept a payload whose keys are Strings as well as Symbols: callers who parse
+    # the gateway's JSON themselves get string keys, and every lookup here is by
+    # symbol. Silently returning nils for a string-keyed payload is how a caller
+    # ends up signing a digest full of blanks.
+    def self.symbolize(hash)
+      raise ArgumentError, "signing payload must be a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+    end
+
+    private_class_method :typehash_for, :symbolize
+
+    def self.hex_to_bytes(hex)
+      h = hex.start_with?("0x") ? hex[2..] : hex
+      [h].pack("H*")
+    end
+
+    def self.abi_address(address)
+      ("\x00" * 12) + hex_to_bytes(address)
+    end
+
+    def self.uint256_to_bytes32(value)
+      hex = Integer(value).to_s(16).rjust(64, "0")
+      [hex].pack("H*")
+    end
+
+    def self.bytes_to_hex(bytes)
+      "0x#{bytes.unpack1('H*')}"
+    end
+
+    private_class_method :hex_to_bytes, :abi_address, :uint256_to_bytes32, :bytes_to_hex
+
+    def self.hash_domain(domain)
+      Eth::Util.keccak256(
+        DOMAIN_TYPEHASH +
+        Eth::Util.keccak256(domain.name) +
+        Eth::Util.keccak256(domain.version) +
+        uint256_to_bytes32(domain.chain_id) +
+        abi_address(domain.verifying_contract)
+      )
+    end
+
+    def self.hash_struct(from:, to:, value:, valid_after:, valid_before:, nonce:, typehash:)
+      Eth::Util.keccak256(
+        typehash +
+        abi_address(from) +
+        abi_address(to) +
+        uint256_to_bytes32(value) +
+        uint256_to_bytes32(valid_after) +
+        uint256_to_bytes32(valid_before) +
+        hex_to_bytes(nonce)
+      )
+    end
+
+    def self.build_digest(domain, from:, to:, value:, valid_after:, valid_before:, nonce:, typehash:)
+      # rubocop:disable Style/StringConcatenation -- these are BINARY byte strings and the
+      # EIP-712 preimage is defined as their concatenation: `+` says that, while
+      # interpolation would coerce each part through to_s and read as text assembly.
+      Eth::Util.keccak256(
+        "\x19\x01" +
+        hash_domain(domain) +
+        hash_struct(from: from, to: to, value: value, valid_after: valid_after,
+                    valid_before: valid_before, nonce: nonce, typehash: typehash)
+      )
+      # rubocop:enable Style/StringConcatenation
+    end
+
+    private_class_method :hash_domain, :hash_struct, :build_digest
+
+    # Resolve whatever the caller passed into something that can sign a digest.
+    #
+    # The seam exists so the raw secret does not have to be materialised as a Ruby
+    # String in the calling process: pass a private-key String (unchanged), an
+    # Eth::Key, or ANY object responding to #sign(digest) -> 65-byte hex — a KMS or
+    # HSM client, a remote signer, a hardware wallet bridge. This SDK builds the
+    # EIP-712 digest and hands only that over; it never needs the key material
+    # itself, which is what makes "the server must never hold the buyer's key"
+    # implementable rather than aspirational. (#10)
+    def self.signer_for(private_key)
+      return private_key if private_key.respond_to?(:sign)
+
+      unless private_key.is_a?(String)
+        raise ArgumentError,
+              "expected a private key String or an object responding to #sign(digest), " \
+              "got #{private_key.class}"
+      end
+
+      Eth::Key.new(priv: private_key.delete_prefix("0x"))
+    end
+
+    private_class_method :signer_for
+
+    def self.do_sign(private_key, domain, from:, to:, value:, valid_after:, valid_before:, nonce:, typehash:)
+      digest = build_digest(domain, from: from, to: to, value: value, valid_after: valid_after,
+                                    valid_before: valid_before, nonce: nonce, typehash: typehash)
+
+      sig       = signer_for(private_key).sign(digest)
+      sig_bytes = [sig.to_s.delete_prefix("0x")].pack("H*")
+
+      # A custom signer that returns something else would otherwise produce a
+      # signature with v: nil, which only fails later in #to_hex with nothing
+      # pointing at the signer.
+      unless sig_bytes.bytesize == 65
+        raise ArgumentError,
+              "the signer returned #{sig_bytes.bytesize} bytes, expected 65 " \
+              "(r || s || v as hex)"
+      end
+
+      Eip3009Signature.new(
+        v: sig_bytes.getbyte(64),
+        r: bytes_to_hex(sig_bytes[0, 32]),
+        s: bytes_to_hex(sig_bytes[32, 32])
+      )
+    end
+
+    private_class_method :do_sign
+
+    # Build and sign the EIP-1559 (type-2) transaction described by a prepare
+    # step's +unsigned_transaction+ and return the signed raw transaction as a
+    # 0x-prefixed hex string, ready for the matching submit call.
+    #
+    # The gateway never holds private keys: it returns the transaction *fields*
+    # (chain id, nonce, to, value, data, gas, fees) and the client assembles and
+    # signs the transaction locally.
+    #
+    #   tx  = client.payments.authorize_prepare(rail0_id)
+    #   raw = Rail0::Signing.sign_transaction(tx[:unsigned_transaction], PAYER_PRIVATE_KEY)
+    #   client.payments.authorize(rail0_id, { signed_transaction: raw })
+    #
+    # @param unsigned_transaction [String, Hash] The +unsigned_transaction+ JSON
+    #   string from a prepare response (a pre-parsed Hash is also accepted).
+    # @param private_key [String] Signer's private key (0x-prefixed or raw hex).
+    # @return [String] 0x-prefixed RLP-encoded signed transaction.
+    def self.sign_transaction(unsigned_transaction, private_key)
+      f = unsigned_transaction.is_a?(String) ? JSON.parse(unsigned_transaction) : unsigned_transaction
+      f = f.transform_keys(&:to_s)
+
+      tx = Eth::Tx.new(
+        chain_id:     Integer(f.fetch("chain_id")),
+        nonce:        Integer(f.fetch("nonce")),
+        priority_fee: Integer(f.fetch("max_priority_fee_per_gas")),
+        max_gas_fee:  Integer(f.fetch("max_fee_per_gas")),
+        gas_limit:    Integer(f.fetch("gas_limit")),
+        to:           f.fetch("to"),
+        value:        Integer(f["value"] || 0),
+        data:         f["data"].to_s
+      )
+
+      # Deliberately narrower than the digest signers above: Eth::Tx#sign needs a
+      # full Eth::Key (it asks for an EIP-155 v derived from the chain id, not a bare
+      # digest signature), so an arbitrary #sign(digest) object cannot serve here.
+      # An Eth::Key is accepted so a caller holding one doesn't have to export it
+      # back to a String.
+      tx.sign(private_key.is_a?(Eth::Key) ? private_key : Eth::Key.new(priv: private_key.delete_prefix("0x")))
+      "0x#{tx.hex}"
+    end
+
+    # Sign the EIP-3009 payload using the signing_payload returned by POST /payments.
+    #
+    # This is the simplest entry point: pass the full signing_payload from the create response
+    # and a private key — all fields are read directly from the payload without any manual
+    # reconstruction. (The payload's inner domain/message keep EIP-712 camelCase — chainId,
+    # verifyingContract, validAfter, validBefore — which this reads directly.)
+    #
+    #   resp = client.payments.create(
+    #     chain_id: 84532, mode: "authorize",
+    #     amount: "100.00", token: "0x...", payer: "0x...", payee: "0x..."
+    #   )
+    #   sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, resp[:signing_payload])
+    #   client.payments.sign(resp[:rail0_id], { signature: sig.to_hex })
+    #
+    # @param private_key [String] Payer's private key (0x-prefixed hex).
+    # @param signing_payload [Hash] The signingPayload hash from the create response.
+    # @return [Eip3009Signature]
+    def self.sign_payload(private_key, signing_payload)
+      payload = symbolize(signing_payload)
+      d = symbolize(payload[:domain])
+      m = symbolize(payload[:message])
+
+      domain = TokenDomain.new(
+        name:               d[:name],
+        version:            d[:version],
+        chain_id:           d[:chainId],
+        verifying_contract: d[:verifyingContract]
+      )
+
+      th = typehash_for(payload[:primaryType])
+
+      do_sign(
+        private_key, domain,
+        from:         m[:from],
+        to:           m[:to],
+        value:        m[:value].to_i,
+        valid_after:  m[:validAfter].to_i,
+        valid_before: m[:validBefore].to_i,
+        nonce:        m[:nonce],
+        typehash:     th
+      )
+    end
+
+    # Sign a raw EIP-3009 transferWithAuthorization message.
+    #
+    # For RAIL0 payment flows prefer {sign_payload} which reads all fields from the
+    # API-returned signingPayload. Use this method only when you need full control over
+    # the message fields (e.g. integrating with a contract directly).
+    #
+    # @param private_key [String] Payer's private key (0x-prefixed or raw hex).
+    # @param domain [TokenDomain]
+    # @param params [SignTransferParams]
+    # @return [Eip3009Signature]
+    def self.sign_transfer_with_authorization(private_key, domain, params)
+      do_sign(
+        private_key, domain,
+        from:         params.from,
+        to:           params.to,
+        value:        params.value,
+        valid_after:  params.valid_after,
+        valid_before: params.valid_before,
+        nonce:        params.nonce,
+        # Explicit, not defaulted: this method is BY NAME the transferWithAuthorization
+        # one. Removing the default from do_sign means no path can inherit a typehash
+        # it never asked for.
+        typehash:     TRANSFER_TYPEHASH
+      )
+    end
+
+    # REMOVED — see {sign_payload}.
+    #
+    # These two rebuilt the EIP-3009 digest from a payment record: they read
+    # from/value/validBefore off the payment, hardcoded `validAfter = 0` and `to =
+    # the RAIL0 contract`, and took do_sign's default (Transfer) typehash. That
+    # re-imports into the client the contract versioning the gateway exists to
+    # absorb — only the gateway knows which contract version a given payment lives
+    # on, and the version selects the typehash, the domain AND the field layout.
+    #
+    # The cost is invisible until it is expensive: rail0#58 moves authorize/charge
+    # to ReceiveWithAuthorization, at which point {sign_payload} follows the gateway
+    # by construction while these two would keep signing the old typehash — a valid
+    # signature over a digest the token refuses, reported as success, failing
+    # on-chain after gas.
+    #
+    # They raise rather than being deleted outright so the migration path arrives
+    # with the failure instead of a bare NoMethodError. (#7)
+    REMOVED_MESSAGE =
+      "Rail0::Signing.%s was removed: it rebuilt the EIP-3009 digest from a payment " \
+      "record, which signs the WRONG digest as soon as the contract's payload changes " \
+      "(rail0#58 moves authorize/charge to ReceiveWithAuthorization). Use " \
+      "Rail0::Signing.sign_payload(private_key, create_response[:signing_payload]) — " \
+      "the gateway builds the payload, clients sign it verbatim."
+    private_constant :REMOVED_MESSAGE
+
+    def self.sign_authorize(_params = nil)
+      raise NotImplementedError, format(REMOVED_MESSAGE, "sign_authorize")
+    end
+
+    def self.sign_charge(_params = nil)
+      raise NotImplementedError, format(REMOVED_MESSAGE, "sign_charge")
+    end
+  end
+end

data/lib/rail0/stablecoins.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Rail0
+  # Stablecoin addresses and capabilities for supported EVM networks.
+  #
+  # eip3009 — transferWithAuthorization (Circle / USDC standard). Required by RAIL0.
+  # eip2612 — permit (ERC-20 extension).
+  # bridged  — bridge-wrapped variant that may not support either extension.
+  module Stablecoins
+    # Static metadata for a single stablecoin on a specific chain.
+    StablecoinInfo = Struct.new(:address, :decimals, :eip3009, :eip2612, :bridged, keyword_init: true)
+
+    # A chain's ID plus its token registry.
+    ChainStablecoins = Struct.new(:chain_id, :tokens, keyword_init: true)
+
+    # Token returned by {eip3009_tokens} and {eip2612_tokens}.
+    StablecoinToken = Struct.new(:symbol, :address, :decimals, keyword_init: true)
+
+    # Registry of known stablecoin addresses and capabilities across supported EVM chains.
+    REGISTRY = {
+      "ethereum" => ChainStablecoins.new(
+        chain_id: 1,
+        tokens: {
+          "USDC"  => StablecoinInfo.new(address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", decimals: 6,  eip3009: true,  eip2612: false),
+          "EURC"  => StablecoinInfo.new(address: "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c", decimals: 6,  eip3009: true,  eip2612: false),
+          "PYUSD" => StablecoinInfo.new(address: "0x6c3ea9036406852006290770BEdFcAbA0e23A0e8", decimals: 6,  eip3009: true,  eip2612: false),
+          "USDT"  => StablecoinInfo.new(address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6,  eip3009: false, eip2612: false),
+          "DAI"   => StablecoinInfo.new(address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", decimals: 18, eip3009: false, eip2612: true)
+        }
+      ),
+      "base" => ChainStablecoins.new(
+        chain_id: 8453,
+        tokens: {
+          "USDC"  => StablecoinInfo.new(address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6, eip3009: true,  eip2612: false),
+          "EURC"  => StablecoinInfo.new(address: "0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42", decimals: 6, eip3009: true,  eip2612: false),
+          "USDbC" => StablecoinInfo.new(address: "0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA", decimals: 6, eip3009: false, eip2612: false, bridged: true)
+        }
+      ),
+      "polygon" => ChainStablecoins.new(
+        chain_id: 137,
+        tokens: {
+          "USDC"   => StablecoinInfo.new(address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", decimals: 6,  eip3009: true,  eip2612: false),
+          "USDC.e" => StablecoinInfo.new(address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", decimals: 6,  eip3009: true,  eip2612: false, bridged: true),
+          "USDT"   => StablecoinInfo.new(address: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F", decimals: 6,  eip3009: false, eip2612: false),
+          "DAI"    => StablecoinInfo.new(address: "0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063", decimals: 18, eip3009: false, eip2612: false)
+        }
+      ),
+      "arbitrumOne" => ChainStablecoins.new(
+        chain_id: 42161,
+        tokens: {
+          "USDC"   => StablecoinInfo.new(address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", decimals: 6,  eip3009: true,  eip2612: false),
+          "USDC.e" => StablecoinInfo.new(address: "0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8", decimals: 6,  eip3009: false, eip2612: false, bridged: true),
+          "USDT"   => StablecoinInfo.new(address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", decimals: 6,  eip3009: false, eip2612: false),
+          "DAI"    => StablecoinInfo.new(address: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1", decimals: 18, eip3009: false, eip2612: true)
+        }
+      ),
+      "optimism" => ChainStablecoins.new(
+        chain_id: 10,
+        tokens: {
+          "USDC"   => StablecoinInfo.new(address: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", decimals: 6,  eip3009: true,  eip2612: false),
+          "USDC.e" => StablecoinInfo.new(address: "0x7F5c764cBc14f9669B88837ca1490cCa17c31607", decimals: 6,  eip3009: false, eip2612: false, bridged: true),
+          "USDT"   => StablecoinInfo.new(address: "0x94b008aA00579c1307B0EF2c499aD98a8ce58e58", decimals: 6,  eip3009: false, eip2612: false),
+          "DAI"    => StablecoinInfo.new(address: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1", decimals: 18, eip3009: false, eip2612: true)
+        }
+      ),
+      "avalanche" => ChainStablecoins.new(
+        chain_id: 43114,
+        tokens: {
+          "USDC"   => StablecoinInfo.new(address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", decimals: 6, eip3009: true,  eip2612: false),
+          "USDC.e" => StablecoinInfo.new(address: "0xA7D7079b0FEaD91F3e65f86E8915Cb59c1a4C664", decimals: 6, eip3009: false, eip2612: false, bridged: true),
+          "USDT"   => StablecoinInfo.new(address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7", decimals: 6, eip3009: false, eip2612: false)
+        }
+      ),
+      "celo" => ChainStablecoins.new(
+        chain_id: 42220,
+        tokens: {
+          "USDC" => StablecoinInfo.new(address: "0xcebA9300f2b948710d2De3250b7Ad3e4aFb0e50a", decimals: 6,  eip3009: true, eip2612: false),
+          "cUSD" => StablecoinInfo.new(address: "0x765DE816845861e75A25fCA122bb6898B8B1282a", decimals: 18, eip3009: true, eip2612: false),
+          "cEUR" => StablecoinInfo.new(address: "0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73", decimals: 18, eip3009: true, eip2612: false)
+        }
+      )
+    }.freeze
+
+    # Returns the registry entry for a chain, or +nil+ if the chain is unknown.
+    #
+    # Supported chain names: "ethereum", "base", "polygon", "arbitrumOne",
+    # "optimism", "avalanche", "celo".
+    #
+    # @param chain [String]
+    # @return [ChainStablecoins, nil]
+    def self.chain_info(chain)
+      REGISTRY[chain]
+    end
+
+    # Returns all tokens on a chain that support EIP-3009 (transferWithAuthorization).
+    # These are the tokens compatible with RAIL0.
+    #
+    # @param chain [String]
+    # @return [Array<StablecoinToken>]
+    def self.eip3009_tokens(chain)
+      tokens_supporting(chain, :eip3009)
+    end
+
+    # Returns all tokens on a chain that support EIP-2612 (permit).
+    #
+    # @param chain [String]
+    # @return [Array<StablecoinToken>]
+    def self.eip2612_tokens(chain)
+      tokens_supporting(chain, :eip2612)
+    end
+
+    def self.tokens_supporting(chain, capability)
+      c = REGISTRY[chain] or return []
+      c.tokens.each_with_object([]) do |(symbol, info), arr|
+        if info.public_send(capability)
+          arr << StablecoinToken.new(symbol: symbol, address: info.address, decimals: info.decimals)
+        end
+      end
+    end
+
+    private_class_method :tokens_supporting
+  end
+end