rail0-sdk 1.5.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 106a0758b1da0b740e9c6e78fb83ffa9cdbfb53d562c2784b67d544aba2d58c3
-  data.tar.gz: '09690a456b1bb50bd573944a3ef9b7f980748bb32eb76ce7c17312a70914cf7a'
+  metadata.gz: 861d8ebab53accbd5a962ed1cb040a91461841b63722077b93374291f8de66bd
+  data.tar.gz: e7d22a5a5d2e9ad6a22149427195b1d7d341e15da84e1d858f453d343859b771
 SHA512:
-  metadata.gz: b0e50c24f6276cb4ba23c812dcc8bc7f3b58cf92715855518bb0a76725c3393959487eb29e59794312bd0ccaab49148b436d5c1873cdeb5029db32f5f5a15ef1
-  data.tar.gz: 59463fad22c007aea05412ade646a21c051db20a85f886bc62897442c810f3c1d3d0f295f03c252c691661be958e8d3f729e7aacbdc0af4a7613a5d13e626483
+  metadata.gz: b926413fd2b987d43b60b78216506baa56eb8954c3d51c7ba2e61a977e597a250c2b961772a27fba93bca1a2f08b036250c15111ecac692823e3ab84548f2004
+  data.tar.gz: a43b612c63ea9114034c4e80eeccb9670758bfecae1267efe5568f322475adfc8dcdf2f935b35f40d9cfcf8559b94b1e65a00b36093c937bf5ac6a385920ba5c

data/README.md

@@ -78,12 +78,18 @@ payment = client.payments.create(
 rail0_id = payment[:rail0_id]
 
 # 2. Payer signs the EIP-3009 payload off-chain and deposits the signature.
-sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, payment[:signing_payload])
+#    payment: is what the authorization is CHECKED against before the key signs it
+#    (see "What sign_signing_payload verifies").
+sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], BUYER_PRIVATE_KEY, payment: payment)
 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 +101,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 +115,59 @@ 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 an address and is the payment's
+`rail0_contract` (an empty or missing `to` — which would sign a contract creation — is
+always refused, even by the deprecated blind form),
+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 no `rail0_contract` or 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.
+
+**What `sign_signing_payload` verifies, and why.** The EIP-3009 authorization the payer
+signs after `create` (and the payee signs in refund phase 1) is the more dangerous of the
+two artifacts: the **token** honours it on its own, with no RAIL0 involvement, for up to
+its `value` — so an endpoint that answered with `{from: you, to: attacker, value: your
+whole balance}` used to get exactly that signed. `sign_signing_payload(signing_payload,
+key, payment:, amount: nil)` checks it first, against data you already hold:
+`message.from` is your key's address, `domain.chainId` the payment's `chain_id`,
+`domain.verifyingContract` the payment's `token`, `message.to` its `rail0_contract`, and
+`message.value` **exactly** the amount — `amount:` scaled by the payment's `decimals` when
+you pass one (a refund), otherwise the payment's own base-unit `amount` (a created
+payment). The first mismatch raises `Rail0::TxVerify::RefusedSignature` ("refusing to
+sign: …", naming the field) and nothing is signed. It fails closed: a payment record
+missing `chain_id`, `token`, `rail0_contract` or an amount to compare is refused, and so
+are unknown `decimals` and an amount finer than the token's. The payload is still signed
+verbatim (typehash from its own `primaryType`). Not checked, as in the CLI: the validity
+window and `message.nonce` (recomputing it needs the deployment's `VERSION()`, which no
+payment response carries), and `to` and the decimals come from the same gateway. The
+residual is an authorization for the right token, chain and signer, for exactly the
+amount you asked. `sign_payload(key, signing_payload)` without `payment:` still signs
+blindly and is **deprecated** (`:deprecated`-category warning); with `payment:` it is
+`sign_signing_payload`. `Rail0::PayloadVerify.verify(signing_payload, payment:, signer:,
+amount: nil)` runs the check on its own.
+
 Wallets that sign **and** broadcast in one step (e.g. MetaMask via
 `eth_sendTransaction`) skip steps 2–3 and report the hash instead:
 
@@ -184,8 +238,8 @@ auth = client.auth.login(private_key: "0x…", domain: "api.rail0.xyz")
 # admin is always a boolean (verify too): true only for an account holding the
 # operator grant, false otherwise (visibility only). account_id/name are nil for an
 # account-less session.
-# login embeds chain_id 1 by default; pass chain_id: to match a gateway whose
-# SIWE_CHAIN_ID policy differs (e.g. login(private_key:, domain:, chain_id: 5042002)).
+# login embeds chain_id 1 by default; the gateway also accepts the id of any chain it
+# has active (GET /blockchains), e.g. login(private_key:, domain:, chain_id: 5042002).
 
 authed = Rail0::Client.new(
   base_url: "https://api.rail0.xyz",
@@ -461,12 +515,16 @@ transactions, so a bulk action can skip busy rows without a `get(id)` each.
 
 ```ruby
 # Phase 1 — amount only → returns a signing payload for the payee to sign.
+#           The authorization is checked against the payment and the refund amount
+#           (payment = client.payments.get(rail0_id)) before the key signs it.
 p1  = client.payments.refund_prepare(rail0_id, amount: "20.00")
-sig = Rail0::Signing.sign_payload(MERCHANT_PRIVATE_KEY, p1[:signing_payload])
+sig = Rail0::Signing.sign_signing_payload(p1[:signing_payload], MERCHANT_PRIVATE_KEY,
+                                          payment: payment, amount: "20.00")
 
 # 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 })
 ```
 
@@ -479,12 +537,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 })
 ```
 
@@ -764,17 +825,25 @@ 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_signing_payload(signing_payload, signer, payment:, amount: nil)` | Verify the EIP-3009 payload from a create/refund response against the payment, then sign it verbatim — the recommended path, and the only one that follows the gateway across contract versions |
+| `sign_payload(signer, signing_payload, payment: nil, amount: nil)` | The same signer; with `payment:` it is `sign_signing_payload`, without it signs blindly (**deprecated**) |
+| `Rail0::PayloadVerify.verify(signing_payload, payment:, signer:, amount: nil)` | The payload pre-sign check on its own |
+| `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
 require "rail0/signing"
-sig = Rail0::Signing.sign_payload(BUYER_PRIVATE_KEY, payment[:signing_payload])
-client.payments.sign(rail0_id, { signature: sig.to_hex })
+payment = client.payments.create(chain_id: 84532, mode: "authorize", amount: "50.00", token: TOKEN,
+                                 payer: BUYER, payee: MERCHANT)
+sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], BUYER_PRIVATE_KEY, payment: payment)
+client.payments.sign(payment[:rail0_id], { signature: sig.to_hex })
+# A hostile payload — another `to`, a larger `value`, another token — raises instead:
+#   Rail0::TxVerify::RefusedSignature: refusing to sign: the authorization is for
+#   999999999999 base units but you asked for 50000000
 ```
 
-**The gateway builds the payload; you sign it verbatim.** `sign_payload` takes the
+**The gateway builds the payload; you sign it verbatim.** `sign_signing_payload` takes the
 typehash from the payload's `primaryType` and every field from its `message` — only
 the gateway knows which contract version a payment lives on, and the version selects
 the typehash, the EIP-712 domain and the field layout. An unrecognised `primaryType`
@@ -786,20 +855,24 @@ digest from a payment record. They raise with a pointer here.
 
 ### Signing without a raw key
 
-`sign_payload` and `sign_transfer_with_authorization` accept a private-key String,
-an `Eth::Key`, or **any object responding to `#sign(digest)`** that returns a
-65-byte hex signature — a KMS or HSM client, a remote signer, a hardware-wallet
+`sign_signing_payload`, `sign_payload` and `sign_transfer_with_authorization` accept a
+private-key String, an `Eth::Key`, or **any object responding to `#sign(digest)`** that
+returns a 65-byte hex signature — a KMS or HSM client, a remote signer, a hardware-wallet
 bridge. The SDK builds the EIP-712 digest and hands only that over, so the secret
 need never be materialised as a String in your process:
 
 ```ruby
 class KmsSigner
   def sign(digest) = MyKms.sign(key_id: KEY_ID, digest: digest)  # -> "0x…" (65 bytes)
+  def address = KMS_KEY_ADDRESS  # what message.from is checked against
 end
 
-sig = Rail0::Signing.sign_payload(KmsSigner.new, payment[:signing_payload])
+sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], KmsSigner.new, payment: payment)
 ```
 
+The checked form needs the signer's address to compare with the authorization's `from`,
+so a custom signer must also respond to `#address` (an `ArgumentError` says so otherwise).
+
 `sign_transaction` is narrower on purpose: `Eth::Tx#sign` derives an EIP-155 `v`
 from the chain id, so it needs a full `Eth::Key` (a String or an `Eth::Key`), not a
 bare digest signer.
@@ -945,6 +1018,8 @@ lib/rail0/
   backoff.rb           Rail0::Backoff — retry delays and 429 jitter
   webhook_signature.rb Rail0::WebhookSignature — delivery verification
   signing.rb           EIP-3009 + EIP-1559 signing (requires 'eth')
+  tx_verify.rb         Rail0::TxVerify — pre-sign check of an unsigned transaction
+  payload_verify.rb    Rail0::PayloadVerify — pre-sign check of an EIP-3009 signing payload
   stablecoins.rb       stablecoin address registry
   dispute_reasons.rb   generated Rail0::DisputeReasons — the dispute-reason dictionary
   types.rb             generated Struct docs of the gateway schema (reference only)

data/lib/rail0/error_hints.rb

@@ -20,14 +20,15 @@ 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
-    # expected chain id would turn every hint into a probe.
+    # expectation: that endpoint is unauthenticated, so echoing the allow-list would
+    # turn every hint into a probe. siwe_chain_mismatch may point at GET /blockchains:
+    # the accepted chain ids (1 plus every active catalog chain) are public there anyway.
     "siwe_domain_not_allowed" => "sign with the origin the front-end is served from, and have it added to the gateway's SIWE domain allow-list",
     "siwe_uri_mismatch" => "the message's uri host must equal its own domain",
-    "siwe_chain_mismatch" => "use the chain id the client library sends - this login is off-chain and nominal",
+    "siwe_chain_mismatch" => "sign with chain id 1 (what the SDK's signing helpers send) or the id of a chain the gateway has active (GET /blockchains) - usually a hand-built message or a wallet on an unsupported or deactivated network",
     "siwe_proof_expired" => "get a fresh nonce and sign again",
     # Address-wide, not one token: "sign in again", not "that token is dead".
     "sessions_revoked" => "every session issued before this address's revoke-all cutoff is refused - sign in again",
@@ -79,6 +80,35 @@ 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",
+    # Ported from rail0-go / rail0-ts, which carried these five and this table did not.
+    "validation_failed" => "a parameter is invalid — the error detail names the offending field",
+    "invalid_sort" => "that field cannot be sorted on — the error detail names the allowed set",
+    "rate_limited" => "rate limit reached — wait for Retry-After (the time left in the window) and retry",
+    "event_not_found" => "the reported transaction mined but did not perform this operation on this payment — nothing moved; check the hash and prepare the operation again",
+    "submission_timeout" => "the transaction was not mined in time and was recorded as failed — if it mines later, re-report its hash via the operation's submitted endpoint",
+    # From the gateway's error catalog (lib/rail0/error_catalog.rb).
+    "invalid_signature" => "the signature could not be recovered — it is malformed, truncated or has a bad recovery byte; send the 65-byte 0x hex (r || s || v) the signer produced",
+    "nonce_used" => "that sign-in nonce was already consumed — request a fresh one (auth.nonce); each is single-use",
+    "siwe_purpose_mismatch" => "the signed message's statement is for a different flow — login, wallet registration, account claim and revoke-all each need their own exact statement",
+    "transaction_mismatch" => "the submitted transaction's target, calldata, value or chain differs from the one this operation prepared — sign the prepare's unsigned_transaction unmodified",
+    "signing_payload_unavailable" => "the gateway could not build the payer's authorization payload because a chain read failed — retry in a moment (payments.get returns it once available)",
+    "queue_unavailable" => "the gateway's job queue could not be reached, so nothing was enqueued — retry in a moment",
+    "webhook_limit_reached" => "this account already holds the most webhook subscriptions it may have — delete one, or add topics to an existing subscription",
+    # 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/payload_verify.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "tx_verify"
+
+module Rail0
+  # Pre-sign verification of a gateway-built EIP-712 / EIP-3009 +signing_payload+ —
+  # {Rail0::TxVerify}'s counterpart for the authorization rather than the transaction.
+  #
+  # It is the MORE dangerous artifact of the two. A malicious transaction costs gas and
+  # goes through RAIL0; an EIP-3009 authorization is a bearer instrument the TOKEN
+  # honours directly, with no RAIL0 involvement, for up to +message.value+. An endpoint
+  # that answered a refund prepare with +{from: <payee>, to: <attacker>, value: <the
+  # payee's whole balance>}+ used to get exactly that signed by {Signing.sign_payload},
+  # and could replay it against the token.
+  #
+  # Ported from the rail0 CLI's cmd/tx_verify.go (+verifySigningPayload+), which is the
+  # reference for the checks, their order and the wording. In order:
+  #
+  # 1. +message.from+ is the signing key's address — the one comparison whose right-hand
+  #    side is derived locally from the key, so it holds whatever the endpoint claims;
+  # 2. +domain.chainId+ is the payment's +chain_id+;
+  # 3. +domain.verifyingContract+ is the payment's +token+ (for EIP-3009 the domain IS
+  #    the token: this stops an authorization minted against another token the signer
+  #    happens to hold);
+  # 4. +message.to+ is the payment's +rail0_contract+ — a consistency check, the address
+  #    comes from the same gateway;
+  # 5. +message.value+ is EXACTLY the amount asked for, in base units — not a ceiling:
+  #    the gateway asks for the full amount of the operation.
+  #
+  # The payload is still signed VERBATIM: the typehash comes from its own +primaryType+
+  # and the digest from its own message. This only refuses a message whose fields
+  # contradict what the caller asked for. Like the CLI, it does not check +primaryType+
+  # against the contract version (the signer already refuses an unknown one), the
+  # validity window, or +message.nonce+ — recomputing the nonce needs the deployment's
+  # VERSION(), which no payment response carries. The bounded residual is an
+  # authorization for the RIGHT token, on the RIGHT chain, from the RIGHT signer, for
+  # EXACTLY the amount asked for.
+  #
+  # FAIL-CLOSED where the CLI is: the amount check never skips (no amount and no stored
+  # base-unit amount, or unknown decimals, refuses). The CLI skips a check whose
+  # expectation it could not resolve; here every expectation comes from the payment
+  # record the caller passes, which always carries chain_id, token and rail0_contract,
+  # so a record missing one of them refuses rather than skipping.
+  #
+  # Loaded by +rail0/signing+ (TxVerify needs the +eth+ gem), never by +require "rail0"+.
+  module PayloadVerify
+    # Verifies +signing_payload+ against +payment+, BEFORE any key touches it. Raises
+    # {Rail0::TxVerify::RefusedSignature} ("refusing to sign: …", naming the field) on
+    # the first mismatch; returns the payload, symbol-keyed, otherwise.
+    #
+    # @param signing_payload [Hash] the +signing_payload+ of a create, get or refund
+    #   prepare response (string or symbol keys)
+    # @param payment [Hash] the payment record: +chain_id+, +token+, +rail0_contract+,
+    #   and +amount+ (base units) or +decimals+ (to scale +amount:+)
+    # @param signer [String] the address of the key about to sign
+    # @param amount [String, nil] the human decimal you asked for (a refund's amount).
+    #   Scaled by the payment's +decimals+. When nil, the payment's own stored +amount+
+    #   (base units) is the expectation — what the payer of a created payment agrees to.
+    # @return [Hash] the payload, symbol-keyed
+    def self.verify(signing_payload, payment:, signer:, amount: nil)
+      sp, domain, message = parse(signing_payload)
+      pay = payment_fields(payment)
+      refuse("cannot check the authorization without the address of the signing key") if blank?(signer)
+
+      check_from(message[:from], signer.to_s)
+      check_chain(domain[:chainId], pay[:chain_id])
+      check_address(domain[:verifyingContract], pay[:token], "token") do |got, want|
+        "the authorization is against token #{got} but this payment's token is #{want}"
+      end
+      check_address(message[:to], pay[:rail0_contract], "rail0_contract") do |got, want|
+        "the authorization pays #{got} but this payment's RAIL0 contract is #{want}"
+      end
+      check_value(message[:value], expected_base_units(pay, amount))
+      sp
+    end
+
+    def self.parse(signing_payload)
+      refuse("there is no signing payload to check") unless signing_payload.is_a?(Hash)
+      sp = symbolize(signing_payload)
+      domain  = sp[:domain]
+      message = sp[:message]
+      refuse("the signing payload has no domain object") unless domain.is_a?(Hash)
+      refuse("the signing payload has no message object") unless message.is_a?(Hash)
+      [sp, symbolize(domain), symbolize(message)]
+    end
+
+    def self.payment_fields(payment)
+      refuse("cannot check the authorization without the payment it is for") unless payment.is_a?(Hash)
+      symbolize(payment)
+    end
+
+    private_class_method :parse, :payment_fields
+
+    # Check 1: from = the key's own address. An absent +from+ is a mismatch, not a skip.
+    def self.check_from(from, signer)
+      return if same_address?(from, signer)
+
+      refuse("the authorization is from #{from} but the signing key is #{signer}")
+    end
+
+    # Check 2. Both sides may arrive as an Integer or a decimal String.
+    def self.check_chain(got, want)
+      refuse("cannot check the authorization's chain without the payment's chain_id") if blank?(want)
+      return if decimal?(got) && decimal?(want) && Integer(got.to_s, 10) == Integer(want.to_s, 10)
+
+      refuse("the authorization is scoped to chain #{got} but this payment is on chain #{want}")
+    end
+
+    # Checks 3 and 4: an address against the payment record's, case-insensitively (the
+    # gateway may return checksummed addresses). The block words the mismatch.
+    def self.check_address(got, want, field)
+      refuse("cannot check the authorization without the payment's #{field}") if blank?(want)
+      return if same_address?(got, want)
+
+      refuse(yield(got, want))
+    end
+
+    # Check 5: exact equality in base units. A value that is not a plain decimal integer
+    # cannot equal one, so it refuses with the same message rather than being coerced
+    # (the signer's +to_i+ would read "1000000abc" as 1000000).
+    def self.check_value(got, want)
+      return if decimal?(got) && Integer(got.to_s, 10) == Integer(want, 10)
+
+      refuse("the authorization is for #{got} base units but you asked for #{want}")
+    end
+
+    private_class_method :check_from, :check_chain, :check_address, :check_value
+
+    # The base-unit amount the authorization must carry. The caller's own +amount:+ is
+    # the trustworthy side, so it wins and is scaled locally by the payment's decimals;
+    # without one, the payment's stored base-unit amount is what is being agreed to.
+    # Either way it never returns nil: the whole guard exists for this comparison.
+    def self.expected_base_units(pay, amount)
+      if blank?(amount)
+        stored = pay[:amount]
+        return stored.to_s if decimal?(stored)
+
+        refuse("cannot check the authorization's amount without an amount: pass amount: " \
+               "or a payment record carrying its base-unit amount")
+      end
+      if pay[:decimals].nil?
+        refuse("the payment's token decimals are unknown, so the authorization's amount cannot be checked " \
+               "(fetch the payment with payments.get first)")
+      end
+      TxVerify.to_base_units(amount.to_s, Integer(pay[:decimals]))
+    end
+
+    private_class_method :expected_base_units
+
+    def self.refuse(message)
+      raise TxVerify::RefusedSignature, "refusing to sign: #{message}"
+    end
+
+    def self.symbolize(hash)
+      hash.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+    end
+
+    def self.blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def self.decimal?(value)
+      value.is_a?(Integer) ? value >= 0 : value.is_a?(String) && value.match?(/\A\d+\z/)
+    end
+
+    # Both sides must be addresses: two blanks (or two identical non-addresses) are not
+    # a match.
+    def self.same_address?(left, right)
+      TxVerify.address?(left) && TxVerify.address?(right) && left.casecmp(right).zero?
+    end
+
+    private_class_method :refuse, :symbolize, :blank?, :decimal?, :same_address?
+  end
+end

data/lib/rail0/resources/auth.rb

@@ -132,9 +132,9 @@ module Rail0
       #
       # @param private_key [String] 0x-prefixed hex private key of the account wallet.
       # @param domain      [String] Host of the API server (e.g. "api.rail0.xyz").
-      # @param chain_id    [Integer] Chain ID to embed in the SIWE message. Must match
-      #   the gateway's SIWE_CHAIN_ID policy (default 1); override only when the
-      #   gateway is configured with a different login chain.
+      # @param chain_id    [Integer] Chain ID to embed in the SIWE message (default 1).
+      #   The gateway accepts 1 or the id of any chain it has active (GET /blockchains);
+      #   anything else is refused with 422 siwe_chain_mismatch.
       # @return [Hash] { token:, address:, account_id:, name:, expires_at:, admin: }
       def login(private_key:, domain:, chain_id: 1)
         message, signature = sign_proof(private_key, domain, chain_id, LOGIN_STATEMENT)

data/lib/rail0/signing.rb

@@ -13,6 +13,9 @@ ensure
   $VERBOSE = original_verbose
 end
 
+require_relative "tx_verify"
+require_relative "payload_verify"
+
 module Rail0
   # EIP-712 and EIP-3009 signing utilities for RAIL0 payments.
   #
@@ -25,7 +28,7 @@ module Rail0
   # ## 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])
+  #   sig  = Rail0::Signing.sign_signing_payload(resp[:signing_payload], BUYER_PRIVATE_KEY, payment: resp)
   #   client.payments.sign(resp[:rail0_id], { signature: sig.to_hex })
   #
   module Signing
@@ -61,7 +64,7 @@ module Rail0
     # 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`.
+    # SDK consumes it. Use {sign_signing_payload} with the gateway's `signing_payload`.
     SignPaymentParams = Struct.new(
       :private_key, :payment, :nonce, :contract_address, :token_domain,
       keyword_init: true
@@ -233,25 +236,66 @@ 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)
 
+      # Even on the deprecated blind path: Eth::Tx treats a nil or "" `to` as a
+      # contract creation and signs it, which would have this key deploy whatever init
+      # code the gateway put in `data`. No RAIL0 operation is ever a creation.
+      unless TxVerify.address?(f["to"].to_s.strip)
+        raise TxVerify::RefusedSignature,
+              "refusing to sign: the transaction's `to` #{f['to'].inspect} is not an address " \
+              "(an empty `to` would deploy a contract)"
+      end
+
       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"),
+        to:           "0x#{f['to'].to_s.strip[2..]}",
         value:        Integer(f["value"] || 0),
         data:         f["data"].to_s
       )
@@ -261,28 +305,83 @@ 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
 
+    # Verify, then sign, the EIP-3009 +signing_payload+ of a create, get or refund
+    # prepare response. The checked form — prefer it over the bare {sign_payload}.
+    #
+    # Before the key touches the payload, {Rail0::PayloadVerify.verify} holds it to
+    # +payment:+: +message.from+ is this key's address, +domain.chainId+ the payment's
+    # chain, +domain.verifyingContract+ its token, +message.to+ its RAIL0 contract, and
+    # +message.value+ exactly the amount — +amount:+ scaled by the payment's +decimals+
+    # when given (a refund), else the payment's stored base-unit +amount+ (the payer of a
+    # created payment). A mismatch raises {Rail0::TxVerify::RefusedSignature} naming the
+    # field, and nothing is signed. Everything compared is already in hand: no extra
+    # gateway call. The payload is then signed verbatim, as {sign_payload} does.
+    #
+    #   payment = client.payments.create(chain_id: 84532, mode: "authorize", amount: "100.00", ...)
+    #   sig = Rail0::Signing.sign_signing_payload(payment[:signing_payload], BUYER_PRIVATE_KEY,
+    #                                             payment: payment)
+    #   client.payments.sign(payment[:rail0_id], { signature: sig.to_hex })
+    #
+    #   payment = client.payments.get(rail0_id)
+    #   p1  = client.payments.refund_prepare(rail0_id, amount: "50.00")
+    #   sig = Rail0::Signing.sign_signing_payload(p1[:signing_payload], MERCHANT_PRIVATE_KEY,
+    #                                             payment: payment, amount: "50.00")
+    #
+    # The key is a private-key String, an Eth::Key, or any object responding to
+    # +#sign(digest)+ AND +#address+ — the address is what +message.from+ is checked
+    # against, so a remote signer (KMS, HSM) must expose the address it signs for.
+    #
+    # @param signing_payload [Hash] the response's +signing_payload+
+    # @param private_key [String, Eth::Key, #sign] the signer
+    # @param payment [Hash] the payment record the authorization is for
+    # @param amount [String, nil] the human decimal asked for (refund); nil = the payment's amount
+    # @return [Eip3009Signature]
+    def self.sign_signing_payload(signing_payload, private_key, payment:, amount: nil)
+      signer = signer_for(private_key)
+      unless signer.respond_to?(:address)
+        raise ArgumentError,
+              "the checked signer needs the key's address to compare with the authorization's `from`: " \
+              "pass a key String or Eth::Key, or a signer responding to #address"
+      end
+
+      PayloadVerify.verify(signing_payload, payment: payment, signer: signer.address.to_s, amount: amount)
+      sign_verbatim(signer, signing_payload)
+    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,
+    # 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 })
+    # With +payment:+ it is {sign_signing_payload}: the payload is VERIFIED against the
+    # payment first. Without it the payload is signed BLINDLY — a compromised or
+    # misconfigured endpoint could have this key sign an authorization the token honours
+    # on its own, for any amount up to the key's balance. 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 private_key [String] Payer's private key (0x-prefixed hex).
+    # @param private_key [String, Eth::Key, #sign] Signer (a private key, 0x-prefixed hex).
     # @param signing_payload [Hash] The signingPayload hash from the create response.
+    # @param payment [Hash, nil] The payment record the authorization is for.
+    # @param amount [String, nil] The human decimal asked for (refund).
     # @return [Eip3009Signature]
-    def self.sign_payload(private_key, signing_payload)
+    def self.sign_payload(private_key, signing_payload, payment: nil, amount: nil)
+      return sign_signing_payload(signing_payload, private_key, payment: payment, amount: amount) if payment || amount
+
+      warn("Rail0::Signing.sign_payload without payment: signs the gateway's authorization blindly " \
+           "and is deprecated; use sign_signing_payload(signing_payload, key, payment:) so it is " \
+           "verified first", uplevel: 1, category: :deprecated)
+      sign_verbatim(private_key, signing_payload)
+    end
+
+    # Signs a payload exactly as the gateway built it: domain, typehash (from its own
+    # primaryType, never guessed) and message fields all come from the payload.
+    def self.sign_verbatim(private_key, signing_payload)
       payload = symbolize(signing_payload)
       d = symbolize(payload[:domain])
       m = symbolize(payload[:message])
@@ -308,9 +407,11 @@ module Rail0
       )
     end
 
+    private_class_method :sign_verbatim
+
     # Sign a raw EIP-3009 transferWithAuthorization message.
     #
-    # For RAIL0 payment flows prefer {sign_payload} which reads all fields from the
+    # For RAIL0 payment flows prefer {sign_signing_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).
     #
@@ -334,7 +435,7 @@ module Rail0
       )
     end
 
-    # REMOVED — see {sign_payload}.
+    # REMOVED — see {sign_signing_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 =
@@ -355,7 +456,8 @@ module Rail0
       "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]) — " \
+      "Rail0::Signing.sign_signing_payload(create_response[:signing_payload], private_key, " \
+      "payment: create_response) — " \
       "the gateway builds the payload, clients sign it verbatim."
     private_constant :REMOVED_MESSAGE
 

data/lib/rail0/tx_verify.rb

@@ -0,0 +1,311 @@
+# 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 an address and 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, and an empty +to+ (a contract creation) always refuses;
+    # 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+, a payment with no
+    # +rail0_contract+ or 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
+
+      check_to(fields["to"], pay[:rail0_contract])
+    end
+
+    # Check 5. +to+ used to be compared only when it was present: an absent, nil or ""
+    # +to+ skipped the check, and Eth::Tx signs a transaction with no recipient as a
+    # CONTRACT CREATION — the calldata becomes init code run by the signing key, which
+    # deploys whatever the gateway sent from the merchant's own account. So an empty or
+    # malformed +to+ refuses outright, and so does a payment record with no
+    # +rail0_contract+ to compare it with: every RAIL0 operation is a call to that one
+    # contract, and nothing else here can tell a legitimate recipient from a hostile one.
+    def self.check_to(to_field, rail0_contract)
+      to = to_field.to_s.strip
+      refuse("the transaction has no `to` address; signing it would deploy a contract") if to.empty?
+      refuse("the transaction's `to` #{to.inspect} is not an address") unless address?(to)
+      if rail0_contract.nil?
+        refuse("cannot check the transaction's `to` without the payment's rail0_contract " \
+               "(fetch the payment with payments.get first)")
+      end
+      return if same_address?(to, rail0_contract)
+
+      refuse("transaction is addressed to #{to} but this payment's RAIL0 contract is #{rail0_contract}")
+    end
+
+    # A 20-byte, 0x-prefixed hex address, any case (prefix included). Shared with
+    # {Rail0::PayloadVerify} and the signer, which applies it even to the deprecated
+    # blind form.
+    def self.address?(value)
+      value.is_a?(String) && value.match?(/\A0x\h{40}\z/i)
+    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, :check_to, :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.
+    # Public because {Rail0::PayloadVerify} scales the caller's amount the same way.
+    #
+    # @param human [String] a decimal amount as the caller typed it ("1.5")
+    # @param decimals [Integer] the token's decimals
+    # @return [String] the amount in base units
+    # @raise [RefusedSignature] when it is not a plain decimal, or is finer than +decimals+
+    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
+
+    # 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

@@ -348,20 +348,83 @@ module Rail0
       keyword_init: true
     )
 
-    # The whole account record, as an operator reads it (Full entity: GET /accounts, POST /accounts, and
-    # GET/PATCH /accounts/{account_id} for an admin session): every column plus `admin` and the derived
-    # `status`.
+    # 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).
-      :claimed_at,    # When the merchant claimed the account at POST /claim; null while it is pending its claim.
       :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 and claimed_at together: pending_claim (not yet claimed, not operational), active (claimed and active) or deactivated (switched off by an operator, claimed or not).
+      :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
     )
 
@@ -414,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.1"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -44,6 +44,7 @@ files:
 - lib/rail0/dispute_reasons.rb
 - lib/rail0/error_hints.rb
 - lib/rail0/http_client.rb
+- lib/rail0/payload_verify.rb
 - lib/rail0/request.rb
 - lib/rail0/resources/accounts.rb
 - lib/rail0/resources/analytics.rb
@@ -59,6 +60,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