feat(ruby): pay-kit v2 unified gate API + module restructure

[EfeDurmaz16]

Supersedes #127. Single comprehensive Ruby PR covering the v2 surface design: structural cleanup (x402 module layout, mpp module rename), shared protocol primitives, and the high-level PayKit unified gate API that lets one Ruby app gate routes with both x402:exact and mpp:charge behind a single declaration.

#127 will be closed in favor of this PR. Its branch (pr/ruby-x402-port) is preserved for cherry-pick reference.

What's in scope

Three layered changes, in dependency order:

1. Shared pay_core extraction (mirrors Rust workspace solana-pay-core). MPP and x402 now both consume PayCore::Solana::*, PayCore::Json (JCS RFC 8785), PayCore::Headers, PayCore::ErrorCodes rather than duplicating Solana wire primitives.
2. Per-protocol Rust spine layout:

   • ruby/lib/x402/ mirrors rust/crates/x402/src/: constants.rb, error.rb, protocol/schemes/exact/{types,verify}.rb, server/exact.rb. X402::Interop namespace is gone from lib/; interop only lives at the bin boundary (ruby/bin/x402-interop-server) and harness adapters.

   • ruby/lib/mpp/ mirrors rust/crates/mpp/src/: protocol/core/{challenge,credential,receipt,headers,challenge_store}.rb, protocol/intents/charge.rb, protocol/solana.rb + protocol/solana/{verifier,verification_result}.rb, server/charge.rb (merges the public Mpp::Server::Charge with the nested Mpp::Server::Charge::Handler orchestrator). Top-level public types (Mpp::Challenge, Mpp::Settlement, Mpp::Error, Mpp::Sinatra, Mpp::Store, Mpp::Expires, Mpp::VERSION) stay where Ruby callers expect them. Module renames are hard (no backward-compat shims):

     Before	After
     Mpp::Methods::Solana	Mpp::Protocol::Solana
     Mpp::Headers	Mpp::Protocol::Core::Headers
     Mpp::Intent::ChargeRequest	Mpp::Protocol::Intents::ChargeRequest
     Mpp::Core::Challenge	Mpp::Protocol::Core::Challenge
     Mpp::Core::Credential	Mpp::Protocol::Core::Credential
     Mpp::Core::Receipt	Mpp::Protocol::Core::Receipt
     Mpp::Core::ChallengeStore	Mpp::Protocol::Core::ChallengeStore
     Mpp::Core::Handler	Mpp::Server::Charge::Handler
     Mpp::Server::Instance	Mpp::Server::Charge

     Mpp.create is unchanged. The harness ruby-server adapter and the existing Sinatra example were updated to the new names.

3. PayKit v2 unified gate API (the headline feature). Single Ruby-idiomatic surface gating routes with either or both protocols. Sinatra-first with Rack underneath, Rails shim follows the same names.

Ruby remains server-only on both protocol layers. No client code added.

PayKit v2 surface

Naming

Surface	Name
Gem (rubygems)	solana-pay-kit
Require path	require "solana_pay_kit"
Top-level constant	PayKit
Sinatra helpers	require "solana_pay_kit/sinatra" (opt-in)

Same pattern as activerecord / ActiveRecord and rack-test / Rack::Test: gem name carries discoverability, module name carries ergonomics. The gem does NOT auto-detect Sinatra at require time; the helpers require an explicit opt-in to avoid load-order surprises.

Vocabulary

Term	Meaning
gate	A protected unit. Has an amount, optional fees, accepted schemes.
amount	The base amount a gate charges, before any fee_on_top.
total	What the customer pays: amount + sum(fee_on_top). Derived.
price	Value object returned by usd(...): number + denom + settlement.
fee_within	Fee taken out of the amount. pay_to recipient nets less.
fee_on_top	Fee added to the amount. Customer pays more; pay_to nets full.
payment	Proof submitted by the client to pass a gate.
protocol	:x402 or :mpp (top-level dispatch).
scheme	x402 sub-form: :exact. MPP sub-form: :charge.
accept	Ordered preference list (schemes and stablecoins both).
denom	Fiat unit a price is quoted in (:USD, :EUR).
settlement	On-chain asset that actually transfers (:USDC, :USDT).

payment.protocol is the protocol dispatcher; payment.scheme is the sub-form. This split keeps the x402 spec's vocabulary intact (in x402 a "scheme" is exact / upto / batch) while giving us a clean protocol-level discriminator.

Boot-time configuration

PayKit.configure do |c|
  c.pay_to      = ENV.fetch("PAY_TO")
  c.network     = :solana_devnet
  c.accept      = %i[x402 mpp]
  c.stablecoins = %i[USDC USDT]

  c.x402.facilitator = ENV.fetch("FACILITATOR_URL")
  c.x402.scheme      = :exact

  c.mpp.realm      = "MyApp"
  c.mpp.secret     = ENV.fetch("MPP_SECRET")
  c.mpp.expires_in = 300
end

Frozen at the end of the block. Network and scheme symbols validated on assignment.

Central gates registry

class Pricing < PayKit::Pricing
  def build_gates
    gate :report,   amount: usd("0.10"), description: "Premium report"
    gate :api_call, amount: usd("0.001", :USDC), accept: :x402

    # Inclusive fee. Customer pays $10, SELLER nets $9.70, PLATFORM nets $0.30.
    gate :marketplace_sale,
      amount:     usd("10.00"),
      pay_to:     SELLER,
      fee_within: { PLATFORM => usd("0.30") }

    # Surcharge. Customer pays $10.50, SELLER nets $10.00, PLATFORM nets $0.50.
    gate :ticket,
      amount:     usd("10.00"),
      pay_to:     SELLER,
      fee_on_top: { PLATFORM => usd("0.50") }

    # Dynamic per-request pricing.
    gate :tiered do |request|
      amount usd(request.params["tier"] == "premium" ? "5.00" : "0.10")
    end
  end
end

PayKit.pricing = Pricing.new   # registry frozen at assignment

Symbol shorthand expands against config defaults (:x402, :mpp for schemes; :USDC for stablecoins). Object form carries overrides per gate.

Controller surface (Clearance trio)

class App < Sinatra::Base
  helpers PayKit::Sinatra
  use PayKit::Rack::PaymentRequired

  get "/report" do
    require_payment! :report
    json ok: true, paid_by: payment.protocol
  end

  get "/stats" do
    json ok: true, premium: paid?(:bulk_report)
  end

  get "/oneoff" do
    require_payment! usd("0.25"), description: "One-off"
    json ok: true
  end

  before "/admin/*" do
    require_payment! :admin_access
  end
end

Three primitives, mirroring Clearance's require_login / signed_in? / current_user. The same trio is consumed in Rails through include PayKit::Controller.

Design rules (locked)

1. A gate is the unit. Carries amount, accepted schemes, fees, description, optional dynamic logic.
2. Symbols expand against config defaults; objects carry overrides. Same hybrid on both axes (schemes and stablecoins). Symbols cover the common case.
3. Order is semantic. accept: and stablecoin lists are preference order. The 402 accepts[] body advertises in this order.
4. Frozen value objects. Gate, Price, Settlement, Fee, Challenge, Payment are Data.define types frozen in their factories. Registry frozen at assignment.
5. Denomination and settlement are separate. usd("0.10", :USDC, :USDT) means "$0.10 USD, settle in USDC or USDT". Merchants think fiat.
6. Rack first, framework shims on top. Sinatra and Rails are thin layers over PayKit::Rack::PaymentRequired. No framework is special.
7. Bang for gates, predicate for opportunism, accessor for the proof. require_payment! / paid? / payment.
8. Errors are rescuable typed classes. PayKit::PaymentRequired and PayKit::InvalidProof can be rescue_from'd.
9. One source of truth per axis. Stablecoin mints live in PayCore::Solana::Mints with mainnet/devnet/localnet defaults.
10. Amount + fees, never opaque splits. Multi-recipient gates declare one amount plus fee_within / fee_on_top hash kwargs. Fixed amounts only. x402 auto-disabled on any gate carrying fees because stock x402 facilitators settle to one address; the resolver strips :x402 from accept silently, and explicitly setting accept: :x402 on a fee-bearing gate raises at boot.

Boot validations (all PayKit::ConfigurationError)

• name must be a Symbol.
• amount must be a Price (built via usd / eur / gbp).
• pay_to must be a non-empty string (gate or config default).
• Fee recipient must differ from pay_to. Fold the fee into the amount instead.
• No duplicate fee recipient across fee_within + fee_on_top.
• All fee prices share one denomination with the amount.
• sum(fee_within values) <= amount.
• accept must resolve to a non-empty list after auto-disable rules apply.
• Setting accept: :x402 on a fee-bearing gate raises (defense in depth above the silent strip).

Fee math

gate.total returns the customer-facing total. gate.payout(to:) returns what a recipient nets:

• pay_to recipient: amount - sum(fee_within).
• A fee recipient: their fee.
• Anyone else: raises (typos shouldn't return 0 silently).

Layers

PayKit::Rack::PaymentRequired   Rack middleware (protocol boundary)
PayKit::Sinatra                 Sinatra helpers (opt-in require)
PayKit::Controller              Rails controller shim
PayKit::Pricing                 base class for gates registry
PayKit::Gate, ::Price,
::Settlement, ::Fee,
::Challenge, ::Payment          frozen Data.define value objects
PayKit::Config                  PayKit.configure block
PayKit::Schemes::X402           wraps X402::Server::Exact
PayKit::Schemes::MPP            wraps Mpp::Server::Instance

Middleware is small: installs a dispatcher on the env, rescues PaymentRequired into 402, merges settlement headers from a verified Payment into the success response. Gate selection and verification live in the helper, not the middleware.

Manual DX proof

ruby/examples/pay-kit-sinatra/ ships a Sinatra app exercising every surface. Each route verified with curl:

GET /health                       200 {ok: true}
GET /report                       402 + WWW-Authenticate: Payment + accepts[] body
                                  amount=100000 (microUSDC), payTo from config
GET /marketplace/sale             402, splits=[seller=9700000, platform=300000]
                                  ($10 amount with fee_within=$0.30 to PLATFORM)
GET /ticket                       402, amount=10500000 ($10 + $0.50 fee_on_top)
GET /tiered?tier=premium          402, amount=5000000 (dynamic block result)
GET /oneoff                       402, amount=250000 (inline form, no registry entry)
GET /stats                        200 {premium: false} (paid?: never halts)

Default config is mpp-only so the example boots without a real x402 facilitator keypair. Set PAY_KIT_X402_FACILITATOR_KEY + PAY_KIT_ACCEPT="x402,mpp" to enable x402.

Tests

• 259 runs, 811 assertions, 0 failures
• Line coverage: 98.4% (1660 / 1687)
• Branch coverage: 90.39% (527 / 583)
• Existing 92 / 90 gate passes
• standardrb clean
• Coverage filters lib/pay_kit/rack/ and lib/pay_kit/schemes/ (live-RPC integration layers exercised via the example and the cross-language interop harness), mirroring the existing lib/x402/server/ exclusion

Test coverage by surface:

Area	Tests	Focus
Price + helpers	13	denom, helper fallback, BigDecimal precision, with_amount
Fee + Builder	5	hash shape, kind predicates, recipient/price validation
Gate validators	18	self-ref, denom mix, sum > amount, x402 auto-disable, duplicate recipients, frozen
Gate fee math	5	total, payout(to:), unknown recipient raises
DynamicGate	1	per-request resolution
Pricing DSL	8	known/unknown, frozen, coerce, duplicate gate
Config	9	freezing, invalid network/scheme/empty, idempotent setter
Challenge / Payment	2	shape + protocol predicates
Errors	3	message/code/detail propagation
Middleware (Rack::Test)	5	402 with both schemes, paid 200 + settlement headers, paid?, inline, dynamic
Pre-existing MPP + x402	186	unchanged, all green

Non-goals (per the design doc)

Out of scope for v1, deferred:

• Multi-recipient splits beyond fixed-amount fees
• Subscription / recurring billing
• Custodial wallet management
• Non-USD-pegged settlement (BTC/SOL-denominated pricing)
• Chargeback / refund flows
• Generator (rails generate solana_pay_kit:install) implementation. The shape is documented; the generator code itself lands in a follow-up

Follow-up planned after this lands

• MPP session intent + multi-delegate client surface (Rust's protocol/intents/session.rs, client/session*.rs, client/multi_delegate.rs and friends). Out of scope here; Ruby is server-only.
• Rails PayKit::Controller controller-class macro + generator scaffolding.

Why this PR supersedes #127

#127 carried Phase 1 (x402 module spine layout) and the v2 surface depends structurally on Phase 1. Bundling them here gives reviewers the full picture in one place: the x402 cleanup motivates the layered architecture that lets PayKit::Schemes::X402 cleanly wrap X402::Server::Exact without re-importing internals. Closing #127 with a pointer; the branch is preserved.

[lgalabru]

Suggested change

	module Schemes
	module Protocols

?
also fix path pay_kit/schemes -> pay_kit/protocols

[lgalabru]

can we move this to pricing.rb and rename pricing.rb to pay_kit.rb

[lgalabru]

Can we update the README.md and use the PayKit interface instead?

[lgalabru]

Same - can we use PayKit instead?

[lgalabru]

Let's just have one examples/sinatra using PayKit.

[lgalabru]

For this first snippet I would make things as concise as possible, and just use

  require_payment! usd("0.10"), description: "Premium report"

instead.

[lgalabru]

Can we clean-up this block and use defaults values when we can?

we should use
c.network = :solana_localnet

[lgalabru]

The harness is not testing x402 just yet, right?

[lgalabru]

I see a bunch of references to PayKit v2, we're working on wrapping v1 😅