rail0-sdk 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06dc80b9fc301df5fb28259087c18ceae341e047418d6c26855a17fc2076c0e8
-  data.tar.gz: ee45ee4241b861c2443af42dc3453a824e1d5974c3accb872f0d03b9356959d3
+  metadata.gz: e046261654c0f0d93915dd0ac7003e78f224115748e697581cac6020c4ea4003
+  data.tar.gz: f9fea94c35a6b996732e0bbdc538361a229134edaa4f52bc6a010e1dfd55b871
 SHA512:
-  metadata.gz: 4a41a60e24ca27221b91e4c35021636cd8f5b134810369354f653b947f9578124c666c09005cc13f25b0f121262d06ff209f97bc637fcf20f2ea8fab5e616c0a
-  data.tar.gz: 3459c91f1e3ed2b9a2c3ede420e004d63c44d2fdf0def948b49e781d7b7f6b4bf00ac7e2c92c5d5b141c46704245c4aed6daed2f5c560199a39f1ed9b7137c24
+  metadata.gz: dcb35d580188aef4a5e6b36878e6e8b3da40dddd671a792eb3275f4baad286636ec6f00e6284d1a0263c6ec764d539e17d8c85ea1904b77f3f1326e8929174fd
+  data.tar.gz: 592f3db30a8c9ecdc755f5b64e9dc0a69166ca73f6b51efcae2c348fb28e60d39b148b41b3cd54015012837c7a8987583d3bc6621f6ef82a4bca3e8b14381526

data/README.md

@@ -82,8 +82,12 @@ sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, payment[:signing_payload])
 client.payments.sign(rail0_id, { signature: sig.to_hex })
 
 # 3. Payee prepares + broadcasts the on-chain authorize tx (signs it locally).
-prep = client.payments.authorize_prepare(rail0_id)
-raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], MERCHANT_PRIVATE_KEY)
+#    payment:/operation: are what the gateway's transaction is CHECKED against before
+#    the key signs it (see "Payment lifecycle"); `payment` is the record read from the gateway.
+payment = client.payments.get(rail0_id)
+prep    = client.payments.authorize_prepare(rail0_id)
+raw     = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], MERCHANT_PRIVATE_KEY,
+                                          payment: payment, operation: "authorize")
 client.payments.authorize(rail0_id, { signed_transaction: raw })   # HTTP 202 (async)
 
 # 4. Poll until the authorization confirms.
@@ -95,7 +99,8 @@ end
 
 # 5. Payee captures the escrowed funds (partial capture is supported).
 cap = client.payments.capture_prepare(rail0_id, "50.00")
-raw = Rail0::Signing.sign_transaction(cap[:unsigned_transaction], MERCHANT_PRIVATE_KEY)
+raw = Rail0::Signing.sign_transaction(cap[:unsigned_transaction], MERCHANT_PRIVATE_KEY,
+                                      payment: payment, operation: "capture", amount: "50.00")
 client.payments.capture(rail0_id, { signed_transaction: raw })
 ```
 
@@ -108,12 +113,34 @@ Each on-chain operation is a `prepare` → `submit` pair:
 
 1. **prepare** — `client.payments.<op>_prepare(...)` returns a transaction whose
    `unsigned_transaction` is the EIP-1559 field-set to sign.
-2. **sign** — `Rail0::Signing.sign_transaction(unsigned, private_key)` returns the
-   signed raw tx.
+2. **sign** — `Rail0::Signing.sign_transaction(unsigned, private_key, payment:, operation:, amount:)`
+   verifies the transaction against the payment record, then returns the signed raw tx.
 3. **submit** — `client.payments.<op>(id, { signed_transaction: raw })` broadcasts
    it. The gateway acknowledges with HTTP 202 and confirms asynchronously — poll
    `client.payments.get(id)` until the status settles.
 
+**What `sign_transaction` verifies, and why.** The gateway builds the EIP-1559
+transaction and your key signs it, so a compromised or misconfigured endpoint could
+otherwise have that key sign anything — an `approve(spender, MAX)` on the token, a
+`capture` answered to a `void` prepare, a capture for more than you asked. Given
+`payment:` (the record from `payments.get`) and `operation:`, `sign_transaction` checks
+the transaction **before** the key touches it, against data you already hold (no extra
+request): `value` is zero (every RAIL0 operation is value-0), `chain_id` is the
+payment's chain, `from` is your key's address, `to` is the payment's `rail0_contract`,
+the 4-byte selector is the RAIL0 function for `operation:` (the selectors are derived
+from the contract's function signatures, `Rail0::TxVerify::SELECTORS`, and pinned
+against its ABI in the spec suite), the first calldata word is the payment's `rail0_id`,
+and — for `capture` and `refund` — the amount word equals `amount:` scaled by the
+payment's `decimals`. The first mismatch raises `Rail0::TxVerify::RefusedSignature`
+("refusing to sign: …", naming the field) and no signature is produced. It fails closed:
+a capture/refund with no `amount:`, or a payment with unknown `decimals`, is refused
+rather than skipped. `to` is a consistency check only — the address comes from the same
+gateway — which is why the calldata binding to this payment's id and operation is what
+closes a swapped transaction. Calling `sign_transaction` without `payment:` still signs
+blindly and is **deprecated** (a `:deprecated`-category warning; shown with
+`-W:deprecated`). `Rail0::TxVerify.verify` runs the check on its own, for a signer that
+is not a local key.
+
 Wallets that sign **and** broadcast in one step (e.g. MetaMask via
 `eth_sendTransaction`) skip steps 2–3 and report the hash instead:
 
@@ -327,8 +354,17 @@ client.wallets.balances(account_id, id_or_address, chain_id: 84532) # live on-ch
 `delete` only deactivates (the same as `update(active: false)`; payments name the
 address, so the row stays). Either way the account's **only active wallet** is
 refused with 422 `last_active_wallet` — login resolves the account from a wallet,
-so an account with none could neither act nor add one back. Add or reactivate
-another wallet first.
+so an account with none could neither act nor add one back. Another wallet must
+be active first.
+
+**A session is bound to the wallet it signed in with.** Reads (`list`, `get`,
+`balances`) are account-wide, but `update`, `delete` and the token-holding methods
+act only on the session's own wallet: another wallet of the same account is
+refused with 403 `not_your_wallet`. An operator session is exempt.
+
+> **Adding a wallet is currently unavailable.** The gateway answers every
+> `wallets.create` with 403 `wallet_add_unavailable`. It returns with the merchant
+> wallet-management section, which keeps the request shape and the proof below.
 
 **Registering a wallet needs a SIWE proof-of-ownership of the address being
 added**, not merely the session JWT. `auth.prove_address` runs that handshake and
@@ -457,7 +493,8 @@ sig = Rail0::Signing.sign_payload(MERCHANT_PRIVATE_KEY, p1[:signing_payload])
 
 # Phase 2 — amount + signature → returns the unsigned on-chain tx.
 p2  = client.payments.refund_prepare(rail0_id, amount: "20.00", signature: sig.to_hex)
-raw = Rail0::Signing.sign_transaction(p2[:unsigned_transaction], MERCHANT_PRIVATE_KEY)
+raw = Rail0::Signing.sign_transaction(p2[:unsigned_transaction], MERCHANT_PRIVATE_KEY,
+                                      payment: payment, operation: "refund", amount: "20.00")
 client.payments.refund(rail0_id, { signed_transaction: raw })
 ```
 
@@ -470,12 +507,15 @@ pattern. Like the rest of `/payments` they need a session, but the payer's
 account-less SIWE login is enough:
 
 ```ruby
+payment = client.payments.get(rail0_id)
 prep = client.payments.dispute_prepare(rail0_id, reason: "not_received") # reason optional
-raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], BUYER_PRIVATE_KEY)
+raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], BUYER_PRIVATE_KEY,
+                                       payment: payment, operation: "dispute")
 client.payments.dispute(rail0_id, { signed_transaction: raw })
 # … later …
 prep = client.payments.close_dispute_prepare(rail0_id, reason: "withdrawn") # or omit reason:
-raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], BUYER_PRIVATE_KEY)
+raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], BUYER_PRIVATE_KEY,
+                                       payment: payment, operation: "close_dispute")
 client.payments.close_dispute(rail0_id, { signed_transaction: raw })
 ```
 
@@ -756,7 +796,8 @@ Requires the `eth` gem. No private key ever leaves your process.
 | Method | Use |
 |--------|-----|
 | `sign_payload(signer, signing_payload)` | Sign the EIP-3009 payload from a create/refund response — the recommended path, and the only one that follows the gateway across contract versions |
-| `sign_transaction(unsigned_transaction, key)` | Sign a prepare step's unsigned EIP-1559 transaction; returns the 0x raw tx |
+| `sign_transaction(unsigned_transaction, key, payment:, operation:, amount: nil)` | Verify a prepare step's unsigned EIP-1559 transaction against the payment, then sign it; returns the 0x raw tx. Without `payment:` it signs blindly (**deprecated**) |
+| `Rail0::TxVerify.verify(unsigned_transaction, payment:, operation:, amount: nil, signer: nil)` | The pre-sign check on its own — for a signer that is not a local key |
 | `sign_transfer_with_authorization(signer, domain, params)` | Raw EIP-3009 `TransferWithAuthorization` signer, for talking to a token directly |
 
 ```ruby

data/lib/rail0/error_hints.rb

@@ -20,7 +20,7 @@ module Rail0
     "nothing_to_dispute" => "a dispute needs a merchant-held (refundable) balance",
     "unknown_dispute_reason" => "reason must be a dispute-reason code (Rail0::DisputeReasons.codes(:open) / codes(:close)) or exactly its bytes32 — full_refund is system-only",
     "transaction_not_overwritable" => "a transaction for this operation is already in flight — wait for it to settle",
-    "signer_mismatch" => "the signing key doesn't match the payment's payer/payee",
+    "signer_mismatch" => "the signature recovers to a different wallet than the one that must sign — the payment's payer/payee, or at POST /claim the wallet the onboarding request names",
     # The SIWE BINDING failures, split out of signer_mismatch so a failed login says
     # WHICH part of the proof did not bind (#216). None names the server's own
     # expectation: that endpoint is unauthenticated, so echoing the allow-list or the
@@ -56,9 +56,16 @@ module Rail0
     "payer_must_be_caller" => "the payer must be the signed-in wallet — sign in as the buyer to create its payment",
     "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — reactivate it or sign in with another of the account's wallets",
     "account_deactivated" => "the merchant account is deactivated: void, release and refund still work, but authorize, charge, capture and account changes do not — ask an operator to reactivate it",
+    # A session is bound to the one wallet it signed in with: the account's other wallets
+    # are readable, but not this session's to change (operators are exempt).
+    "not_your_wallet" => "a session can change only the wallet it signed in with — sign in with that wallet to update it, deactivate it or manage its tokens",
+    # POST /accounts/:id/wallets is suspended for every session until the merchant
+    # wallet-management section lands.
+    "wallet_add_unavailable" => "adding a wallet to an account is not available yet — it returns with the merchant wallet-management section",
     # Login resolves the account FROM a wallet, so an account left with no active one
-    # could neither act nor add a wallet back.
-    "last_active_wallet" => "this is the account's only active wallet — add or reactivate another wallet first, then switch this one off",
+    # could neither act nor add a wallet back. Adding a wallet is suspended and a session
+    # changes only its own wallet, so the other wallet has to be reactivated by an operator.
+    "last_active_wallet" => "this is the account's only active wallet — another wallet must be active before this one can be switched off (adding a wallet is not available yet; an operator can reactivate one)",
     "last_admin" => "the change would leave no active operator — grant the operator role to another active account first",
     "not_redrivable" => "only a pending transaction that already holds its signed bytes can be redriven — check the transaction's `redrivable` flag, and submit the signature if it has none",
     "refund_expired" => "the refund window has closed (refundExpiry passed) — refund/dispute is no longer possible",
@@ -72,6 +79,21 @@ module Rail0
     "unknown_token" => "the token isn't configured on this chain",
     "no_active_contract" => "no active RAIL0 contract on that chain",
     "missing_param" => "a required parameter is missing from the request",
+    # Onboarding: POST /signup and POST /claim (the gateway's onboarding flow).
+    # The /admin/onboardings codes (onboarding_not_found, onboarding_completed) are left
+    # out: those routes are the console's, not the SDK's. The link codes never say which
+    # term failed — a stale link has one remedy: the newest email, or a new link.
+    "signup_unavailable" => "self-service sign-up is switched off on this gateway for now — try again later, or ask your RAIL0 contact for an invite",
+    "onboarding_unavailable" => "this gateway has no onboarding secret configured, so it can neither issue nor verify sign-up links — ask the operator",
+    "email_provider_not_configured" => "the gateway has no email provider that delivers, so no link was sent and nothing was saved — ask the operator to configure one",
+    "email_domain_not_allowed" => "this environment emails only its allowed domains (the detail lists them) — use an address on one of them; nothing was saved",
+    "account_email_taken" => "an account with this email already exists — sign in with its wallet, or use another email",
+    "account_wallet_taken" => "this wallet is already registered to an account — sign in with it, or use another wallet",
+    "account_name_taken" => "an account with this name already exists — choose another name",
+    "terms_required" => "the claim needs terms_version: send the version of the terms the merchant accepted",
+    "onboarding_link_invalid" => "the link was altered or its request no longer exists — use the link in the most recent email, or ask for a new one",
+    "onboarding_link_expired" => "the link has expired — sign up again, or ask your RAIL0 contact for a new link",
+    "onboarding_link_superseded" => "a newer link was sent for this request and this one no longer works — use the link in the most recent email",
     # A BARE forbidden is not a party mismatch: the gateway split those into codes of
     # their own (not_the_payee, not_the_payer, wallet_deactivated, account_deactivated,
     # not_your_account) because they need different fixes. This entry kept describing

data/lib/rail0/resources/wallets.rb

@@ -11,6 +11,12 @@ module Rail0
     # with its token holdings nested under +tokens+ (a wallet with no matching
     # tokens is still returned with an empty list). +id_or_address+ accepts either
     # the wallet UUID or its 0x address (unique per account).
+    #
+    # A session is bound to the wallet it signed in with. Reads (list, get, balances)
+    # are account-wide, but update, delete and the token-holding methods act only on
+    # the session's own wallet: another wallet of the same account raises ApiError 403
+    # +not_your_wallet+ (an operator session is exempt). +create+ is suspended for
+    # every session (403 +wallet_add_unavailable+).
     class Wallets
       include Query
 
@@ -51,6 +57,10 @@ module Rail0
 
       # Add a wallet to the account.
       #
+      # CURRENTLY UNAVAILABLE: the gateway answers every session ApiError 403
+      # +wallet_add_unavailable+ until the merchant wallet-management section lands.
+      # The method and its proof shape are kept because that section reuses them.
+      #
       # Requires a SIWE PROOF-OF-OWNERSHIP of the address being added, not merely
       # the session JWT: the gateway verifies that +signature+ recovers to
       # +address+ (422 otherwise), consumes the nonce carried in +message+, and
@@ -77,9 +87,11 @@ module Rail0
         http.post("/accounts/#{segment(account_id)}/wallets", body)
       end
 
-      # Update a wallet's label and/or active status. +active: false+ on the account's
-      # only active wallet raises ApiError 422 +last_active_wallet+: login resolves the
-      # account from a wallet, so an account with none could neither act nor add one back.
+      # Update a wallet's label and/or active status. Only the wallet the session signed
+      # in with: another wallet of the account raises ApiError 403 +not_your_wallet+ (an
+      # operator may change any). +active: false+ on the account's only active wallet
+      # raises ApiError 422 +last_active_wallet+: login resolves the account from a
+      # wallet, so an account with none could neither act nor add one back.
       # @param account_id [String] Account UUID.
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @param label [String, nil] New label.
@@ -93,7 +105,8 @@ module Rail0
       end
 
       # Soft-delete (deactivate) a wallet — the same as +update(active: false)+, so the
-      # account's only active wallet raises ApiError 422 +last_active_wallet+. Returns HTTP 204.
+      # account's only active wallet raises ApiError 422 +last_active_wallet+, and another
+      # wallet than the session's own 403 +not_your_wallet+. Returns HTTP 204.
       # @param account_id [String] Account UUID.
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @return [nil]
@@ -119,6 +132,9 @@ module Rail0
       # Which tokens a wallet accepts, on which chains. This is what GET
       # /payment_methods then exposes to buyers, so a merchant onboarding flow that
       # can create a wallet but not configure its tokens cannot finish. (#12)
+      #
+      # Owner only, and only on the wallet the session signed in with: another wallet
+      # of the same account raises ApiError 403 +not_your_wallet+.
 
       # Accept a token (on a chain) on this wallet.
       #

data/lib/rail0/signing.rb

@@ -13,6 +13,8 @@ ensure
   $VERBOSE = original_verbose
 end
 
+require_relative "tx_verify"
+
 module Rail0
   # EIP-712 and EIP-3009 signing utilities for RAIL0 payments.
   #
@@ -233,15 +235,47 @@ module Rail0
     # (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 })
+    # With +payment:+ and +operation:+ the transaction is VERIFIED before the key
+    # touches it ({Rail0::TxVerify.verify}): zero value, the payment's chain and RAIL0
+    # contract, the key's own address as +from+, the RAIL0 function for +operation+,
+    # this payment's id in the calldata and — for capture and refund — the +amount:+ you
+    # asked for, scaled by the payment's +decimals+. A mismatch raises
+    # {Rail0::TxVerify::RefusedSignature} naming the field, and nothing is signed.
+    # Everything compared is already in hand, so this adds no gateway call.
+    #
+    #   payment = client.payments.get(rail0_id)   # chain_id, rail0_contract, rail0_id, decimals
+    #   tx  = client.payments.capture_prepare(rail0_id, "50.00")
+    #   raw = Rail0::Signing.sign_transaction(tx[:unsigned_transaction], PAYEE_PRIVATE_KEY,
+    #                                         payment: payment, operation: "capture", amount: "50.00")
+    #   client.payments.capture(rail0_id, { signed_transaction: raw })
+    #
+    # Without +payment:+ the transaction is signed BLINDLY — a compromised or
+    # misconfigured endpoint could have this key sign an arbitrary transaction. That
+    # form is DEPRECATED (a +:deprecated+ warning is emitted; enable them with
+    # +Warning[:deprecated] = true+ or +-W:deprecated+) and will be removed in the next
+    # major version.
     #
     # @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).
+    # @param private_key [String, Eth::Key] Signer's private key (0x-prefixed or raw hex).
+    # @param payment [Hash, nil] The payment record the transaction is for.
+    # @param operation [String, Symbol, nil] The operation the prepare was called for.
+    # @param amount [String, nil] The human decimal passed to the prepare (capture/refund).
     # @return [String] 0x-prefixed RLP-encoded signed transaction.
-    def self.sign_transaction(unsigned_transaction, private_key)
+    def self.sign_transaction(unsigned_transaction, private_key, payment: nil, operation: nil, amount: nil)
+      key = private_key.is_a?(Eth::Key) ? private_key : Eth::Key.new(priv: private_key.delete_prefix("0x"))
+
+      if payment || operation
+        # Before the transaction is even assembled: one that fails the check must
+        # leave no signature behind.
+        TxVerify.verify(unsigned_transaction, payment: payment, operation: operation,
+                                              amount: amount, signer: key.address.to_s)
+      else
+        warn("Rail0::Signing.sign_transaction without payment:/operation: signs the gateway's " \
+             "transaction blindly and is deprecated; pass the payment record and the operation " \
+             "so it is verified first", uplevel: 1, category: :deprecated)
+      end
+
       f = unsigned_transaction.is_a?(String) ? JSON.parse(unsigned_transaction) : unsigned_transaction
       f = f.transform_keys(&:to_s)
 
@@ -261,7 +295,7 @@ module Rail0
       # 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")))
+      tx.sign(key)
       "0x#{tx.hex}"
     end
 

data/lib/rail0/tx_verify.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rail0
+  # Pre-sign verification of a gateway-built unsigned transaction.
+  #
+  # +Rail0::Signing.sign_transaction+ used to sign whatever +unsigned_transaction+ a
+  # prepare step returned. A hostile or merely misconfigured gateway endpoint could
+  # therefore have the merchant's own key sign an arbitrary transaction — an
+  # +approve(spender, MAX)+ on the token, a capture answered to a void prepare, a
+  # capture for a larger amount than asked. The checks here run on data the caller
+  # already holds (the payment record, the operation it asked for, the amount it typed)
+  # BEFORE the key touches the transaction, so they add no gateway round-trip. A
+  # mismatch raises {RefusedSignature}, whose message starts with "refusing to sign:"
+  # and names the field; no signature is produced.
+  #
+  # Ported from the rail0 CLI's cmd/tx_verify.go (#63), which is the reference for the
+  # check order and the fail-closed rules. Loaded by +rail0/signing+ (it needs the
+  # +eth+ gem for keccak256), never by +require "rail0"+ alone.
+  module TxVerify
+    # Raised instead of signing. Deliberately not an ArgumentError: the caller's
+    # arguments are fine, it is the GATEWAY's transaction that is not.
+    class RefusedSignature < StandardError; end
+
+    # RAIL0.sol's +Payment+ struct as the ABI encodes it: payer, payee, token, amount
+    # (uint120), authorizationExpiry and refundExpiry (uint48). All static types, so the
+    # tuple is encoded INLINE — six 32-byte words right after the paymentId — which is
+    # what fixes the position of the amount argument below.
+    PAYMENT_TUPLE = "(address,address,address,uint120,uint48,uint48)"
+    private_constant :PAYMENT_TUPLE
+
+    # The eight RAIL0 entry points, keyed by the gateway's wire name for the operation.
+    # Copied from RAIL0.sol; the spec pins the derived selectors against the contract's
+    # compiled +methodIdentifiers+, so a typo here cannot agree with itself.
+    FUNCTION_SIGNATURES = {
+      "authorize"     => "authorize(bytes32,#{PAYMENT_TUPLE},uint8,bytes32,bytes32)",
+      "charge"        => "charge(bytes32,#{PAYMENT_TUPLE},uint8,bytes32,bytes32)",
+      "capture"       => "capture(bytes32,#{PAYMENT_TUPLE},uint256)",
+      "void"          => "void(bytes32,#{PAYMENT_TUPLE})",
+      "release"       => "release(bytes32,#{PAYMENT_TUPLE})",
+      "refund"        => "refund(bytes32,#{PAYMENT_TUPLE},uint256,uint8,bytes32,bytes32)",
+      "dispute"       => "dispute(bytes32,#{PAYMENT_TUPLE},bytes32)",
+      "close_dispute" => "closeDispute(bytes32,#{PAYMENT_TUPLE},bytes32)"
+    }.freeze
+
+    # Operation → the function's 4-byte selector as 8 lowercase hex chars: the first
+    # four bytes of keccak256(signature), computed from the table above rather than
+    # hand-copied.
+    SELECTORS = FUNCTION_SIGNATURES.transform_values do |sig|
+      Eth::Util.keccak256(sig)[0, 4].unpack1("H*")
+    end.freeze
+
+    # Calldata position (in 32-byte words after the selector) of the +uint256 amount+
+    # argument of capture and refund: word 0 is the paymentId, words 1-6 the inline
+    # Payment tuple, so the amount is word 7. Only these two operations take an amount.
+    AMOUNT_WORD = { "capture" => 7, "refund" => 7 }.freeze
+    private_constant :AMOUNT_WORD
+
+    SELECTOR_HEX = 8  # 4-byte selector
+    WORD_HEX     = 64 # 32-byte ABI word
+    private_constant :SELECTOR_HEX, :WORD_HEX
+
+    # Folds the vocabularies an operation arrives in onto the gateway's wire name:
+    # "closeDispute", "close dispute", :close_dispute are one operation.
+    def self.canonical_operation(operation)
+      operation.to_s.strip
+               .gsub(/([a-z0-9])([A-Z])/, '\1_\2')
+               .gsub(/[\s-]+/, "_")
+               .downcase
+    end
+
+    # Verifies a gateway-built +unsigned_transaction+ against what the caller asked for,
+    # BEFORE any key touches it. Raises {RefusedSignature} naming the first field that
+    # disagrees; returns the parsed, string-keyed transaction otherwise.
+    #
+    # In order:
+    # 1. the JSON parses;
+    # 2. +value+ is zero — every RAIL0 operation is value-0, funds move as token
+    #    transfers the contract performs, so a non-zero value is the gateway asking for ETH;
+    # 3. +chain_id+ is the payment's chain;
+    # 4. +from+, when present, is +signer+ (the signing key's address);
+    # 5. +to+ is the payment's +rail0_contract+ — a consistency check (the address comes
+    #    from the same gateway), but it catches a response stitched from two payments;
+    # 6. the 4-byte selector is the RAIL0 function for +operation+, and for capture and
+    #    refund the amount word equals +amount+ scaled by the payment's +decimals+;
+    # 7. the paymentId word is the payment's +rail0_id+.
+    #
+    # Every right-hand side is something the caller supplied or derived locally — never
+    # the prepare response itself. FAIL-CLOSED on what cannot be compared: an unknown
+    # operation, a capture/refund without an +amount+, or a payment with unknown
+    # +decimals+ refuses rather than skips. Only the paymentId comparison is skipped,
+    # when the payment carries no usable +rail0_id+.
+    #
+    # @param unsigned_transaction [String, Hash] the prepare response's field-set
+    # @param payment [Hash] the payment record (from +payments.create+ / +payments.get+)
+    # @param operation [String, Symbol] the operation the prepare was called for
+    # @param amount [String, nil] the human decimal passed to the prepare (capture/refund)
+    # @param signer [String, nil] the address of the key about to sign, or nil to skip
+    # @return [Hash] the transaction, string-keyed
+    def self.verify(unsigned_transaction, payment:, operation:, amount: nil, signer: nil)
+      tx = parse(unsigned_transaction)
+      pay = payment_fields(payment)
+      check_header(tx, pay, signer)
+
+      data = tx["data"].to_s
+      # The operation before the payment id, so a swapped operation is named as such.
+      check_call(data, operation, expected_base_units(pay, operation, amount))
+      check_payment_id(data, pay[:rail0_id])
+      tx
+    end
+
+    # Checks 2-5: the fields outside the calldata.
+    def self.check_header(fields, pay, signer)
+      unless zero_native_value?(fields["value"])
+        refuse("transaction attaches native currency (value=#{fields['value'].inspect}); " \
+               "every RAIL0 operation is value-0")
+      end
+
+      if pay[:chain_id] && !pay[:chain_id].to_i.zero? && fields["chain_id"].to_s != pay[:chain_id].to_s
+        refuse("transaction targets chain #{fields['chain_id']} but this payment is on chain #{pay[:chain_id]}")
+      end
+
+      from = fields["from"].to_s
+      if signer && !from.empty? && !same_address?(from, signer)
+        refuse("transaction is prepared from #{from} but the signing key is #{signer}")
+      end
+
+      to = fields["to"].to_s
+      return unless pay[:rail0_contract] && !to.empty? && !same_address?(to, pay[:rail0_contract])
+
+      refuse("transaction is addressed to #{to} but this payment's RAIL0 contract is #{pay[:rail0_contract]}")
+    end
+
+    def self.parse(unsigned_transaction)
+      tx = unsigned_transaction.is_a?(String) ? JSON.parse(unsigned_transaction) : unsigned_transaction
+      refuse("the unsigned transaction is not an object") unless tx.is_a?(Hash)
+      tx.transform_keys(&:to_s)
+    rescue JSON::ParserError => e
+      refuse("the gateway's unsigned transaction is not valid JSON: #{e.message}")
+    end
+
+    def self.payment_fields(payment)
+      refuse("cannot check the transaction without the payment it is for") unless payment.is_a?(Hash)
+      p = payment.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+      { chain_id: p[:chain_id], rail0_id: p[:rail0_id], rail0_contract: presence(p[:rail0_contract]),
+        decimals: p[:decimals] }
+    end
+
+    def self.presence(value)
+      s = value.to_s
+      s.empty? ? nil : s
+    end
+
+    private_class_method :check_header, :parse, :payment_fields, :presence
+
+    def self.refuse(message)
+      raise RefusedSignature, "refusing to sign: #{message}"
+    end
+
+    # The encodings a zero native value legitimately arrives in — absent, nil, the
+    # number 0, or the string "0" / "0x0". A whitelist, deliberately: anything
+    # unrecognised must refuse the signature rather than be guessed at.
+    def self.zero_native_value?(value)
+      case value
+      when nil then true
+      when Integer then value.zero?
+      when String
+        s = value.strip
+        s.empty? || s == "0" || s.casecmp("0x0").zero?
+      else false
+      end
+    end
+
+    def self.same_address?(left, right)
+      left.to_s.casecmp(right.to_s).zero?
+    end
+
+    private_class_method :refuse, :zero_native_value?, :same_address?
+
+    # Scales the human amount the CALLER typed by the payment's token decimals, for
+    # comparison against the calldata. nil when the operation takes no amount. For one
+    # that does, a missing amount or unknown decimals is a refusal — the whole guard
+    # exists for that comparison, so it must not be skipped.
+    def self.expected_base_units(pay, operation, amount)
+      key = canonical_operation(operation)
+      return nil unless AMOUNT_WORD.key?(key)
+
+      refuse("cannot check the #{key} amount without the amount you asked for") if amount.to_s.strip.empty?
+      if pay[:decimals].nil?
+        refuse("the payment's token decimals are unknown, so the #{key} amount cannot be checked " \
+               "(fetch the payment with payments.get first)")
+      end
+      to_base_units(amount.to_s, Integer(pay[:decimals]))
+    end
+
+    # String math, no Float: "1.5" at 6 decimals is "1500000". More fractional digits
+    # than the token has is a refusal, not a truncation — the gateway 422s such an
+    # amount, so dropping digits would compare against a figure never asked for.
+    def self.to_base_units(human, decimals)
+      s = human.strip
+      refuse("amount #{human.inspect} is not a decimal number") unless s.match?(/\A\d+(\.\d+)?\z/)
+      whole, frac = s.split(".", 2)
+      frac ||= ""
+      if frac.length > decimals
+        refuse("amount #{human.inspect} has #{frac.length} decimal places, but this token has #{decimals}")
+      end
+      (whole + frac.ljust(decimals, "0")).sub(/\A0+(?=\d)/, "")
+    end
+
+    private_class_method :expected_base_units, :to_base_units
+
+    # Asserts the call is the RAIL0 function for +operation+ and, for capture and refund,
+    # that it moves exactly +want_units+ base units.
+    #
+    # Checking the paymentId alone binds the transaction to the right PAYMENT but not to
+    # the right OPERATION: every RAIL0 function takes the paymentId first, so a hostile
+    # endpoint could answer a void prepare with capture calldata (settling the escrow
+    # to the merchant instead of returning it). The selector closes that; the amount
+    # word closes the remaining capture/refund swap — the right function for a
+    # different quantity than the caller typed. Fail-closed: no known selector, or an
+    # amount-taking operation with nothing local to compare, refuses rather than skips.
+    def self.check_call(data, operation, want_units)
+      key  = canonical_operation(operation)
+      want = SELECTORS[key] || refuse("no known RAIL0 function for operation #{operation.to_s.inspect}")
+      raw  = strip_hex(data)
+      refuse("calldata is #{raw.length} hex chars, too short to carry a function selector") if raw.length < SELECTOR_HEX
+      got = raw[0, SELECTOR_HEX]
+      if got != want
+        refuse("the call is #{describe_selector(got)} but you asked to #{key} (#{FUNCTION_SIGNATURES[key]})")
+      end
+
+      word = AMOUNT_WORD[key]
+      return if word.nil?
+
+      refuse("cannot check the #{key} amount without the amount you asked for") if want_units.nil?
+      start = SELECTOR_HEX + (word * WORD_HEX)
+      if raw.length < start + WORD_HEX
+        refuse("calldata is #{raw.length} hex chars, too short to carry the #{key} amount")
+      end
+      got_int  = raw[start, WORD_HEX].to_i(16)
+      want_int = Integer(want_units, 10)
+      return if got_int == want_int
+
+      refuse("the call would #{key} #{got_int} base units but you asked for #{want_int}")
+    end
+
+    # Names a selector for an error message: the RAIL0 function it belongs to when it
+    # is one of ours (the likely shape of a swapped operation), and the bare hex otherwise.
+    def self.describe_selector(selector)
+      op = SELECTORS.key(selector)
+      op ? "#{FUNCTION_SIGNATURES[op].split('(', 2).first}()" : "selector 0x#{selector}"
+    end
+
+    # Asserts the call's first argument is THIS payment's id.
+    #
+    # All eight RAIL0 operations take +bytes32 paymentId+ first, so under ABI encoding
+    # the id always occupies bytes 4..36 of the calldata. A hostile gateway's most
+    # profitable swap is +approve(spender, MAX)+ on the token contract, which this
+    # rejects: approve's first argument is a left-padded address, so it cannot be a
+    # rail0_id. Skipped only when there is no usable rail0_id to compare against.
+    def self.check_payment_id(data, rail0_id)
+      want = strip_hex(rail0_id.to_s)
+      return if want.length != WORD_HEX
+
+      raw = strip_hex(data)
+      if raw.length < SELECTOR_HEX + WORD_HEX
+        refuse("calldata is #{raw.length} hex chars, too short to carry a paymentId")
+      end
+      got = raw[SELECTOR_HEX, WORD_HEX]
+      refuse("the call acts on payment 0x#{got} but you asked for 0x#{want}") if got != want
+    end
+
+    def self.strip_hex(hex)
+      hex.to_s.strip.downcase.delete_prefix("0x")
+    end
+
+    private_class_method :check_call, :describe_selector, :check_payment_id, :strip_hex
+  end
+end

data/lib/rail0/types.rb

@@ -106,7 +106,7 @@ module Rail0
     )
 
     AdminRpcHealthEndpoint = Struct.new(
-      :url,         # String — Scheme, host, port and path only.
+      :url,         # String — The endpoint, as configured.
       :ok,          # Boolean
       :status,      # String
       :error,       # String — Short `Class: first line`; never an upstream body.
@@ -348,6 +348,86 @@ module Rail0
       keyword_init: true
     )
 
+    # The whole account record, as an operator reads it (Full entity: GET /accounts, and GET/PATCH
+    # /accounts/{account_id} for an admin session): every column plus `admin` and the derived `status`.
+    AccountFull = Struct.new(
+      :id,            # String
+      :name,          # String
+      :email,         # String — Stored lowercase.
+      :active,        # Boolean — The operator's switch. false = deactivated.
+      :priority_tip,  # Boolean — The merchant's fee setting (see Account.priority_tip).
+      :created_at,    # String
+      :updated_at,    # String
+      :admin,         # Boolean — Whether the account holds the operator grant (a row in administrators).
+      :status,        # String — One-word reading of active: active, or deactivated (switched off by an operator).
+      keyword_init: true
+    )
+
+    # An onboarding request (Full entity): every column plus the derived `status` and the `creator`.
+    # Never a token or a link: the token is not stored.
+    Onboarding = Struct.new(
+      :id,                 # String — Also the id of the account the claim creates.
+      :origin,             # String
+      :name,               # String
+      :email,              # String — Lowercase.
+      :address,            # String — Lowercase 0x + 40 hex.
+      :created_by,         # The operator account of an invite; null for a sign-up.
+      :link_version,       # Integer — The version of the last link minted; a link for any lower one answers onboarding_link_superseded.
+      :last_sent_at,       # String — When the last send was queued.
+      :send_count,         # Integer — Sends queued in all (0 for a request migrated from a pending account, which has no link in the current format yet).
+      :last_delivered_at,  # When the provider accepted the last send.
+      :last_send_error,    # A short fixed code for why the last send failed (provider_rejected, timeout, email_domain_not_allowed, …); null when it was delivered or is in flight.
+      :expires_at,         # String — When the last link, and the open request, expire.
+      :completed_at,       # When the claim created the account.
+      :terms_version,      # The terms version accepted at the claim.
+      :created_at,         # String
+      :updated_at,         # String
+      :status,             # String
+      :creator,            # The operator who created an invite; null for a sign-up.
+      keyword_init: true
+    )
+
+    # A clash of a request with an account (the value already belongs to it) or with another request not
+    # yet completed.
+    OnboardingConflict = Struct.new(
+      :field,  # String
+      :with,   # String
+      :id,     # String — The account's or the other request's id.
+      keyword_init: true
+    )
+
+    # The mail queued for the request — never its link, which exists only in the mail.
+    QueuedEmail = Struct.new(
+      :kind,    # String
+      :to,      # String
+      :queued,  # Boolean
+      keyword_init: true
+    )
+
+    # An operator's create, reuse or correction.
+    OnboardingOutcome = Struct.new(
+      :onboarding,  # Onboarding
+      :conflicts,   # Array
+      :email,       # QueuedEmail
+      keyword_init: true
+    )
+
+    # A resend or reminder.
+    OnboardingSent = Struct.new(
+      :onboarding,  # Onboarding
+      :email,       # QueuedEmail
+      keyword_init: true
+    )
+
+    # The mail as it would have been sent, rendered by the gateway's template with `<claim link
+    # generated after the request is created>` in place of the link.
+    EmailPreview = Struct.new(
+      :to,       # String
+      :subject,  # String
+      :text,     # String
+      keyword_init: true
+    )
+
     # An operator grant with the people named.
     AdministratorFull = Struct.new(
       :id,          # String
@@ -379,9 +459,10 @@ module Rail0
 
     # One reported policy value.
     PolicySetting = Struct.new(
-      :value,       # The effective value (number, boolean, string, list or map).
-      :env,         # String — The environment variable that sets it; null for a constant.
-      :overridden,  # Boolean — Whether that variable is set in this process.
+      :value,        # The effective value (number, boolean, string, list or map).
+      :env,          # String — The environment variable that sets it; null for a constant.
+      :overridden,   # Boolean — Whether that variable is set in this process.
+      :description,  # String — Plain-text explanation of the entry: what it controls, which part of the gateway reads it and the effect of raising or lowering it, and its unit (from config/policy_descriptions.yml). Every entry has one; older gateways omit the field.
       keyword_init: true
     )
 
@@ -396,6 +477,8 @@ module Rail0
       :siwe,          # Hash
       :fees,          # Hash
       :rpc,           # Hash
+      :onboarding,    # Hash
+      :email,         # Hash
       :generated_at,  # String
       keyword_init: true
     )

data/lib/rail0/version.rb

@@ -5,5 +5,5 @@ module Rail0
   # consumed by path from a sibling checkout, where the number bought nothing: no registry
   # ever served a 1.x, no tag was ever cut, and the one consumer resolves the working tree.
   # Publishing from 1.2.0 would have implied two releases nobody can install.
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -59,6 +59,7 @@ files:
 - lib/rail0/resources/webhooks.rb
 - lib/rail0/signing.rb
 - lib/rail0/stablecoins.rb
+- lib/rail0/tx_verify.rb
 - lib/rail0/types.rb
 - lib/rail0/version.rb
 - lib/rail0/webhook_signature.rb