rail0-sdk 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '078c5043f2867777ccba9da57fe022e3db252cff6010f50dbad7c9dd37b7c8a7'
-  data.tar.gz: e64f79000eeb6b94b78367c223eb33f48ac5ffc23218ac89dffb3b99e23504d1
+  metadata.gz: 7e9c4a0434db81266c43b414c1f3f2f4b6f2466ef7aa9f1f4f1e1406542fabdf
+  data.tar.gz: a01332eba373c295821bd20edaa16076f4ef20b9fdb204064a0c9c378a5b8f1b
 SHA512:
-  metadata.gz: 4030fedd465183a1e4dba618ad1c3d7ff75d667032e3ebce6e7da87aeb4e1c75c9ab1205378d89fd2329a005ceb7f8a1b22ab3504b466e0c06b387117a5736a3
-  data.tar.gz: d894eea1f54c0c8514be643b3fdb7300cdc8c2158dd4c4db0de29b0b8fb09c7226d2910e981c921735a5b5589310484243cc9ddc9b01b92b75692ae68e5c43f0
+  metadata.gz: abc0ca11b0940752160e3503087fd89d62c1e8ba04b5c6412cdef41751b598b25acd988fb52e4b04aa5a2c2e64c6fafdf0a72625eceb98238e0e2abd6a955e55
+  data.tar.gz: 9267bc67421f3aa0867c5c9b24a959679d1c648ea5e9598df149743a06efa76db088ea9f1b21a39a46c0f2974376ceadf783e34a65b59f1d846a5ae603c08464

data/README.md

@@ -301,11 +301,17 @@ logging — it says exactly which sessions died, which `revoked_all: true` canno
 ```ruby
 client.chains.list                                    # GET /blockchains (each chain's :contract is the active RAIL0 deployment, :settlement its measured confirm time)
 client.chains.list(network_type: "testnet", symbol: "ETH")
+Rail0::Resources::Chains.resolve(client.chains.list(network_type: "testnet"), "arc")  # by slug (case-insensitive) or chain id; raises on no match / an ambiguous slug
 client.tokens.list                                    # GET /tokens — every token, retired ones included
 client.tokens.list(chain_id: 84532, symbol: "USDC")
 client.tokens.list(active: true)                      # what a NEW payment may use
 ```
 
+Each chain carries a `slug` (e.g. `"arc"`, shared by its testnet and mainnet, unique per
+`network_type`) and `public_rpc_urls` (keyless RPC endpoints the gateway publishes for
+clients). `Chains.resolve(chains, ref)` picks one by chain id or slug without a request; a
+slug matching both networks in the list raises, so filter with `network_type:` or pass the id.
+
 Each chain's `settlement` is how long an operation on it has taken to confirm **on this
 gateway**, end to end (the chain's finality lag plus the gateway/indexer pipeline):
 `{ p50_seconds:, p90_seconds:, sample_size:, window_days: }`, percentiles of broadcast →
@@ -335,7 +341,7 @@ client.health.get   # GET /health → { status:, api_version:, contract_version:
 
 ## Pagination
 
-Paginated calls return `{ data:, meta: }`. `meta` is `{ page:, per_page:, total:, total_pages:, links: }`.
+Paginated calls return `{ data:, meta: }`. `meta` is `{ page:, per_page:, total:, total_pages:, links:, next_cursor: }`.
 
 `page` is 1-based and bounded to 1..1,000,000 — a value outside is a 400, not an empty
 page. `per_page` defaults to 25 and is capped at 100.
@@ -349,6 +355,22 @@ while page[:meta][:links][:next]
 end
 ```
 
+`payments.list` and `payouts.list` also page by **cursor**: pass `after:` (omit it on the
+first page) and follow `meta[:next_cursor]` until it is `nil`. It walks newest first at a
+constant cost per page and carries no total (`total` reads 0); `page:` or a sort other than
+`-created_at` beside `after:` is 422 `invalid_cursor`. `next_cursor` comes from the
+`x-next-cursor` header, or the Link `next`'s `after` when the header is missing, and is
+`nil` on offset pages.
+
+```ruby
+cursor = nil
+loop do
+  page = client.payouts.list(per_page: 100, after: cursor)
+  page[:data].each { |payout| puts payout[:id] }
+  break unless (cursor = page[:meta][:next_cursor])
+end
+```
+
 ### Idempotent prepares
 
 Every `*_prepare` takes an optional `idempotency_key:`. Without one, a retry that arrives after the first transaction was signed and broadcast opens a **second** one — right for a genuine sequential partial capture, wrong for a retry, and only the caller can tell those apart. Replaying a key returns the first transaction; the same key with different terms is refused `422 idempotency_key_reused`.
@@ -625,12 +647,133 @@ client.payments.submit(id, "capture", { signed_transaction: raw })
 client.payments.submit_by_hash(id, "capture", { transaction_hash: "0x…" })
 ```
 
+## Payouts (JWT)
+
+A payout moves the merchant wallet's balance to a **payout destination** — a deposit
+address at an exchange, Circle Mint, an off-ramp provider or your own custody. It is a
+plain ERC-20 `transfer(address,uint256)` from the wallet, signed by the destination's own
+wallet; rail0 never holds the key. Destination amounts (`reserve_amount`, `min_amount`)
+are **base-unit** strings; the `*_formatted` fields beside them carry the human decimals.
+
+### 1. Register a destination (with the confirmation)
+
+Generate the deposit address at the venue **with the network set to the payout's chain**,
+note the venue's minimum deposit, then register it. `confirm_details:` is required and has
+no default: `true` is the merchant's acceptance of the gateway's `details_v1` text
+(`Rail0::Resources::PayoutDestinations::CONFIRM_DETAILS_TEXT`), recorded with who and when:
+
+> I have checked the address, network, token and minimum deposit on the venue's deposit
+> page and confirm they are correct. Funds sent to a wrong address or network, or below the
+> venue's minimum, may be permanently lost and cannot be recovered by rail0.
+
+Show that text and pass the merchant's answer; anything but `true` is 422
+`confirmation_required` and nothing is saved.
+
+```ruby
+dest = client.payout_destinations.create(
+  wallet_id: WALLET_ID,               # the session's own wallet (uuid or address)
+  chain_id: 5042002, token: USDC, address: VENUE_DEPOSIT_ADDRESS,
+  label: "Kraken", kind: "exchange",  # exchange | circle_mint | self_custody | provider
+  min_amount: "5000000",              # the venue's minimum, base units (5 USDC); omit for none
+  confirm_details: merchant_accepted  # true only once the merchant accepted the text above
+)
+dest[:status]                         # => "unverified"
+
+client.payout_destinations.list(status: "verified")       # paged like payments
+client.payout_destinations.get(dest[:id])
+client.payout_destinations.events(dest[:id])               # audit trail, newest first
+```
+
+### 2. Prove it: proof → confirm
+
+An unverified destination can receive the **proof** amount at most: a small test transfer
+(the gateway's proof amount, raised to `min_amount` when that is higher). Send it, wait for
+it to confirm on-chain, check that the venue **credited** it, then confirm:
+
+```ruby
+proof = client.payouts.prepare(destination_id: dest[:id], purpose: "proof")
+client.payouts.sign_and_submit(proof, MERCHANT_PRIVATE_KEY, destination: dest)
+# … poll client.payouts.get(proof[:id]) until status == "confirmed", check the venue …
+client.payout_destinations.confirm(dest[:id])              # => status "verified"
+```
+
+### 3. Pay out: prepare → verify → sign → submit
+
+`amount` is a **human decimal** or `"all"` (the balance minus the reserve, below). A payout
+below the destination's `min_amount` is refused 422 `payout_below_minimum`.
+
+```ruby
+payout = client.payouts.prepare(destination_id: dest[:id], amount: "250.00")
+client.payouts.sign_and_submit(payout, MERCHANT_PRIVATE_KEY,
+                               destination: dest, amount: "250.00", decimals: 6)
+# 202, now "submitted"; poll client.payouts.get(payout[:id]) (or the payouts.confirmed /
+# payouts.failed webhooks) until it settles
+```
+
+`sign_and_submit` is `Rail0::Signing.sign_payout` + `payouts.submit`. Before the key touches
+the prepared `unsigned_transaction`, `Rail0::PayoutVerify.verify` holds it to exactly:
+`to` = the payout's token, `value` 0, `chain_id` = the payout's chain, and calldata
+`0xa9059cbb` + abi(the payout's address, the payout's base-unit amount) with nothing
+trailing. With `destination:` the payout must also be for that registered destination
+(chain, token, address); with `amount:` + `decimals:` its amount must be exactly the one you
+asked for. Anything else raises `Rail0::TxVerify::RefusedSignature` and nothing is signed or
+sent. There is no blind form.
+
+The two steps apart, or the other way to send:
+
+```ruby
+raw = Rail0::Signing.sign_payout(payout, MERCHANT_PRIVATE_KEY, destination: dest,
+                                 amount: "250.00", decimals: 6)
+client.payouts.submit(payout[:id], { signed_transaction: raw })   # the gateway broadcasts
+
+# A wallet that signs and broadcasts itself: verify, send, then report the hash.
+Rail0::PayoutVerify.verify(payout[:unsigned_transaction], payout: payout, destination: dest,
+                           amount: "250.00", decimals: 6)
+client.payouts.submit_by_hash(payout[:id], { transaction_hash: "0x…" })
+
+client.payouts.resend(payout[:id])  # re-broadcast the stored signed bytes (after a 502)
+client.payouts.cancel(payout[:id])  # an UNSIGNED pending payout only
+client.payouts.list(status: %w[pending submitted], purpose: "payout")
+client.payouts.events(payout[:id])
+```
+
+One pending payout per destination: preparing again replaces it while it is unsigned. Once
+a signed transaction is stored, it may still be mined, so it cannot be re-prepared or
+cancelled (409 `payout_already_signed`): `resend` it and let it settle.
+
+A runnable end-to-end flow (register → proof → confirm → payout → poll) is in
+[`examples/06_payouts.rb`](examples/06_payouts.rb).
+
+### Minimum and reserve
+
+- **Minimum** (`min_amount`): the venue's minimum deposit. Below it the venue may never
+  credit a transfer, so the gateway refuses it. Changing it needs the same confirmation, and
+  raising it above the latest proof takes the verification away (prove it again):
+
+  ```ruby
+  client.payout_destinations.update(dest[:id], min_amount: "10000000", confirm_details: merchant_accepted)
+  client.payout_destinations.update(dest[:id], min_amount: "", confirm_details: merchant_accepted)  # none
+  ```
+
+- **Reserve** (`reserve_amount`): what an `"all"` payout leaves in the wallet so refunds can
+  still be paid. Unset, the gateway's suggestion applies (`suggested_reserve`: the refundable
+  balance of payments still inside their refund window).
+
+  ```ruby
+  client.payout_destinations.update(dest[:id], reserve_amount: "100000000")
+  client.payout_destinations.update(dest[:id], reserve_amount: "")   # back to the suggestion
+  client.payout_destinations.update(dest[:id], active: false)        # disable (true re-enables)
+  ```
+
 ## Webhooks (JWT)
 
 One subscription carries a **set** of topics (see `Rail0::Resources::Webhooks::TOPICS`):
 one shared secret and one circuit breaker for all of them, with each delivery naming the
 event that fired in `X-Rail0-Topic`. Two subscriptions for the same `callback_url` must not
-overlap — the gateway answers 409 and names the topic that collided.
+overlap — the gateway answers 409 and names the topic that collided. The payout topics —
+`payouts.confirmed`, `payouts.failed` (the reason is the payout's `error_code`) and
+`payout_destinations.verified` — carry the same envelope (`id`, `emitted_at`, `topic`) with
+the subject under `payout` or `payout_destination` instead of `payment`/`transaction`.
 
 ```ruby
 hook = client.webhooks.create(
@@ -867,6 +1010,8 @@ Requires the `eth` gem. No private key ever leaves your process.
 | `Rail0::PayloadVerify.verify(signing_payload, payment:, signer:, amount: nil)` | The payload pre-sign check on its own — run it before handing the payload to a browser wallet |
 | `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_payout(payout, key, destination: nil, amount: nil, decimals: nil)` | Verify a prepared payout's ERC-20 transfer (see [Payouts](#payouts-jwt)), then sign it; returns the 0x raw tx. No blind form |
+| `Rail0::PayoutVerify.verify(unsigned_transaction, payout:, destination: nil, amount: nil, decimals: nil, signer: nil)` | The payout pre-sign check on its own — for a wallet that broadcasts itself |
 | `sign_transfer_with_authorization(signer, domain, params)` | Raw EIP-3009 `TransferWithAuthorization` signer, for talking to a token directly |
 
 ```ruby
@@ -1058,6 +1203,7 @@ lib/rail0/
   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
+  payout_verify.rb     Rail0::PayoutVerify — pre-sign check of a payout's ERC-20 transfer
   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)
@@ -1074,6 +1220,8 @@ lib/rail0/
     accounts.rb        the caller's own account profile, read and update (JWT)
     webhooks.rb        webhook subscription management (JWT)
     analytics.rb       account-scoped payment analytics (JWT)
+    payout_destinations.rb payout destinations: register, confirm, update (JWT)
+    payouts.rb         merchant payouts: prepare, sign, submit (JWT)
     query.rb           shared query-string and path-segment helpers
 ```
 
@@ -1115,7 +1263,8 @@ A release is an approved pull request: merging it is what publishes.
    **Or on a feature branch**, to release a change in the same review: run it on a clean
    branch that is pushed, contains `origin/main` and has an open pull request into `main`.
    The bump is committed and pushed on that branch (`chore(release): vX.Y.Z`), the pull
-   request's own title counts toward the version and gets a line in the notes, and the
+   request's own title counts toward the version, gets a line in the notes and gains a
+   ` (release vX.Y.Z)` suffix, and the
    notes go into its description between `<!-- release:start -->` markers — the text above
    them is kept. Re-run it after new commits or a merge of `main`: it refreshes the version
    and the notes instead of bumping twice. One approval then covers the change and its

data/lib/rail0/client.rb

@@ -12,6 +12,8 @@ require_relative "resources/payments"
 require_relative "resources/disputes"
 require_relative "resources/webhooks"
 require_relative "resources/analytics"
+require_relative "resources/payout_destinations"
+require_relative "resources/payouts"
 
 module Rail0
   # Entry point for the RAIL0 SDK.
@@ -48,8 +50,13 @@ module Rail0
     #   @return [Resources::Webhooks] Webhook subscription management (JWT).
     # @!attribute [r] analytics
     #   @return [Resources::Analytics] Account-scoped payment analytics (JWT).
+    # @!attribute [r] payout_destinations
+    #   @return [Resources::PayoutDestinations] Where the merchant's payouts go (JWT).
+    # @!attribute [r] payouts
+    #   @return [Resources::Payouts] Merchant payouts: prepare, sign, submit (JWT).
     attr_reader :auth, :chains, :tokens, :health, :payment_methods,
-                :accounts, :wallets, :payments, :disputes, :webhooks, :analytics
+                :accounts, :wallets, :payments, :disputes, :webhooks, :analytics,
+                :payout_destinations, :payouts
 
     # @param base_url [String] Base URL of the RAIL0 API, e.g. "https://api.rail0.xyz".
     # @param headers [Hash] Default headers merged into every request (e.g. Authorization).
@@ -83,6 +90,8 @@ module Rail0
       @disputes        = Resources::Disputes.new(http)
       @webhooks        = Resources::Webhooks.new(http)
       @analytics       = Resources::Analytics.new(http)
+      @payout_destinations = Resources::PayoutDestinations.new(http)
+      @payouts             = Resources::Payouts.new(http)
       freeze
     end
   end

data/lib/rail0/error_hints.rb

@@ -113,6 +113,26 @@ module Rail0
     "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",
+    # Payouts (gateway#455): the merchant's transfer of its balance to a payout destination.
+    "confirmation_required" => "registering a payout destination, or changing its min_amount, needs confirm_details: true — the merchant's confirmation that they checked the address, network, token and minimum deposit at the venue (PayoutDestinations::CONFIRM_DETAILS_TEXT)",
+    "payout_destination_exists" => "this wallet already has a destination with this address for this token and chain — use it (payout_destinations.list)",
+    "payout_destination_zero_address" => "the zero address cannot receive a payout — register the venue's deposit address",
+    "payout_destination_own_wallet" => "the destination is the paying wallet itself — register the deposit address of the exchange, Circle Mint account or another wallet you control",
+    "payout_destination_is_contract" => "the address is a RAIL0 contract or a token contract on this chain, where funds cannot be recovered — register the venue's deposit address",
+    "payout_destination_disabled" => "the destination is disabled — re-enable it (payout_destinations.update(id, active: true)) or choose another one",
+    "payout_destination_unverified" => "the destination is not verified: send the proof (payouts.prepare(purpose: \"proof\")), wait for it to confirm, check the venue credited it, then payout_destinations.confirm — until then only the proof amount can be sent",
+    "payout_destination_proof_missing" => "the proof transfer has not confirmed on-chain yet — prepare, sign and submit it (purpose: \"proof\"), wait for payouts.get to say confirmed, then confirm the destination",
+    "payout_below_minimum" => "the amount is below the destination's min_amount (the venue may never credit it) — send at least the minimum; for \"all\", the balance after the reserve is below it",
+    "insufficient_balance" => "the wallet does not hold enough of the token for this amount after the refund reserve — the detail names what is available",
+    "payout_limit_reached" => "this wallet reached its hourly payout limit — retry later",
+    "payout_already_signed" => "the payout already holds a signed transaction that may still be mined — resend it (payouts.resend) and let it settle; it cannot be re-prepared or cancelled",
+    "payout_not_pending" => "the payout is already submitted or settled — prepare a new one",
+    "payout_not_signed" => "the payout holds no signed transaction to resend — submit the signed transfer first",
+    "payout_hash_in_use" => "another payout already records this transaction hash — one transaction settles one payout",
+    "foreign_transfer_hash" => "the reported transaction does not move this payout's amount of its token to its destination — report the hash of the transfer you broadcast for this payout",
+    "invalid_amount" => "the amount is not valid: base units (digits only, below 2^120) for reserve_amount/min_amount, a positive decimal within the token's decimals elsewhere",
+    "invalid_transaction" => "the signed transaction could not be decoded, or its sender is not allowed here — sign the prepare's unsigned_transaction unmodified with the right wallet",
+    "unknown_chain" => "that chain id is not configured on this gateway — see chains.list",
     # 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/http_client.rb

@@ -64,7 +64,8 @@ module Rail0
     # headers (not a {data, meta} envelope), so this reads the meta back from the
     # headers and wraps the array. Non-paginated array endpoints (blockchains,
     # tokens, payment_methods) use plain #get instead.
-    # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+    # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total:, total_pages:, links:,
+    #   next_cursor: } } — next_cursor is set only on a cursor-paged list with a next page.
     def get_list(path)
       request(:get, path, nil, paginated: true)
     end

data/lib/rail0/payout_verify.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative "tx_verify"
+
+module Rail0
+  # Pre-sign verification of a payout's +unsigned_transaction+ — {Rail0::TxVerify}'s
+  # counterpart for the merchant payout (POST /payouts/prepare).
+  #
+  # A payout is not a RAIL0 call: it is a plain ERC-20 +transfer(address,uint256)+ from the
+  # merchant's wallet, addressed to the TOKEN contract. For a plain transfer the calldata IS
+  # the money, so nothing in it may be skipped: a gateway endpoint that answered with
+  # +approve(attacker, MAX)+, a transfer to another address, a larger amount, another token
+  # or another chain would otherwise have the merchant's key sign it. Every check below runs
+  # on data the caller already holds, before the key touches the transaction. In order:
+  #
+  # 1. the JSON parses;
+  # 2. +value+ is zero — an ERC-20 transfer attaches no native currency;
+  # 3. +chain_id+ is the payout's +chain_id+;
+  # 4. +from+, when present, is the signing key's address;
+  # 5. +to+ is an address and is the payout's +token+ (case-insensitive) — an empty +to+
+  #    would be a contract creation and always refuses;
+  # 6. +data+ is EXACTLY +0xa9059cbb+ ++ abi(address = the payout's +address+, uint256 = the
+  #    payout's base-unit +amount+), nothing trailing.
+  #
+  # With +destination:+ (the record the merchant registered, from
+  # {Resources::PayoutDestinations#get}) the payout itself is first held to it: same
+  # destination id, chain, token and recipient address — so a payout "for" this destination
+  # that pays elsewhere refuses. With +amount:+ (the human decimal the caller asked
+  # {Resources::Payouts#prepare} for, not "all") the payout's base-unit amount must be exactly
+  # that amount scaled by +decimals:+.
+  #
+  # FAIL-CLOSED: a payout record missing its chain_id, token, address or a base-unit amount,
+  # or an explicit +amount:+ without +decimals:+, refuses rather than skips. A refusal raises
+  # {Rail0::TxVerify::RefusedSignature} ("refusing to sign: …", naming the field).
+  #
+  # Mirrors rail0-admin's lib/onchain-guard.ts (+assertTxTarget+ with a transfer, and
+  # +assertTransferCall+). Loaded by +rail0/signing+, never by +require "rail0"+ alone.
+  module PayoutVerify
+    # The 4-byte selector of ERC-20 +transfer(address,uint256)+ — keccak256 of that
+    # signature, pinned in the spec.
+    TRANSFER_SELECTOR = "a9059cbb"
+
+    # The one function a payout may call.
+    TRANSFER_SIGNATURE = "transfer(address,uint256)"
+
+    WORD_HEX = 64
+    private_constant :WORD_HEX
+
+    # Verifies +unsigned_transaction+ against +payout+ (and +destination+ / +amount+ when
+    # given), BEFORE any key touches it. Raises {Rail0::TxVerify::RefusedSignature} on the
+    # first mismatch; returns the parsed, string-keyed transaction otherwise.
+    #
+    # @param unsigned_transaction [String, Hash] the payout's +unsigned_transaction+
+    # @param payout [Hash] the prepared payout (+chain_id+, +token+, +address+, +amount+)
+    # @param destination [Hash, nil] the registered destination the payout must be for
+    # @param amount [String, nil] the human decimal passed to prepare; nil or "all" skips
+    #   only this comparison (the gateway chose the amount: a proof, or the balance)
+    # @param decimals [Integer, nil] the token's decimals, required with an explicit +amount+
+    # @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, payout:, destination: nil, amount: nil, decimals: nil, signer: nil)
+      tx  = parse(unsigned_transaction)
+      pay = payout_fields(payout)
+      check_destination(pay, destination) unless destination.nil?
+      check_amount(pay[:amount], amount, decimals)
+      check_header(tx, pay, signer)
+      check_call(tx["data"], pay[:address], pay[:amount])
+      tx
+    end
+
+    def self.parse(unsigned_transaction)
+      refuse("the payout carries no unsigned transaction") if blank?(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
+
+    # The payout fields the transaction is held to. Every one is required: for a plain
+    # transfer there is nothing else to compare against.
+    def self.payout_fields(payout)
+      refuse("cannot check the transaction without the payout it is for") unless payout.is_a?(Hash)
+      p = symbolize(payout)
+      refuse("the payout's chain_id is unknown, so the chain cannot be checked") unless decimal?(p[:chain_id])
+      refuse("the payout's token is not an address, so the transfer cannot be checked") unless address?(p[:token])
+      refuse("the payout's address is not an address, so the transfer cannot be checked") unless address?(p[:address])
+      refuse("the payout's amount is not base units, so the transfer cannot be checked") unless decimal?(p[:amount])
+
+      { id: p[:id], destination_id: p[:destination_id], chain_id: Integer(p[:chain_id].to_s, 10),
+        token: p[:token], address: p[:address], amount: Integer(p[:amount].to_s, 10) }
+    end
+
+    private_class_method :parse, :payout_fields
+
+    # The payout must be FOR the destination the merchant registered: the gateway answers
+    # both, but the destination is the record the merchant typed and confirmed, so a payout
+    # that disagrees with it is one stitched from somewhere else.
+    def self.check_destination(pay, destination)
+      refuse("the destination is not a record") unless destination.is_a?(Hash)
+      d = symbolize(destination)
+      check_destination_id(pay[:destination_id], d[:id])
+      unless decimal?(d[:chain_id]) && Integer(d[:chain_id].to_s, 10) == pay[:chain_id]
+        refuse("the payout is on chain #{pay[:chain_id]} but the destination is on chain #{d[:chain_id].inspect}")
+      end
+      unless same_address?(d[:token], pay[:token])
+        refuse("the payout moves token #{pay[:token]} but the destination is for #{d[:token].inspect}")
+      end
+      return if same_address?(d[:address], pay[:address])
+
+      refuse("the payout pays #{pay[:address]} but the destination's address is #{d[:address].inspect}")
+    end
+
+    def self.check_destination_id(got, want)
+      return if blank?(got) || blank?(want) || got.to_s == want.to_s
+
+      refuse("the payout is for destination #{got} but you asked for #{want}")
+    end
+
+    # The caller's own amount, scaled locally, against the payout's base-unit amount. "all"
+    # and nil leave the amount to the gateway (the balance after the reserve, or the proof).
+    def self.check_amount(payout_units, amount, decimals)
+      return if blank?(amount) || amount.to_s.strip.casecmp("all").zero?
+
+      if decimals.nil?
+        refuse("the token's decimals are unknown, so the payout amount #{amount.to_s.inspect} cannot be checked")
+      end
+      want = Integer(TxVerify.to_base_units(amount.to_s, Integer(decimals)), 10)
+      return if want == payout_units
+
+      refuse("the payout moves #{payout_units} base units but you asked for #{want}")
+    end
+
+    private_class_method :check_destination, :check_destination_id, :check_amount
+
+    # Checks 2-5: the fields outside the calldata.
+    def self.check_header(fields, pay, signer)
+      unless TxVerify.zero_native_value?(fields["value"])
+        refuse("transaction attaches native currency (value=#{fields['value'].inspect}); an ERC-20 transfer is value-0")
+      end
+      unless decimal?(fields["chain_id"]) && Integer(fields["chain_id"].to_s, 10) == pay[:chain_id]
+        refuse("transaction targets chain #{fields['chain_id'].inspect} but this payout 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.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)
+      return if same_address?(to, pay[:token])
+
+      refuse("transaction is addressed to #{to} but this payout's token is #{pay[:token]}")
+    end
+
+    # Check 6: the calldata, decoded word by word so the refusal names what differs, then
+    # its length — a transfer is exactly selector + two words, and anything appended is
+    # refused rather than ignored (the token would ignore it; the signature would not).
+    def self.check_call(data, address, units)
+      raw = data.to_s.strip.downcase.delete_prefix("0x")
+      refuse("calldata is not hex") unless raw.match?(/\A\h*\z/)
+      refuse("calldata is #{raw.length} hex chars, too short to carry a function selector") if raw.length < 8
+      selector = raw[0, 8]
+      unless selector == TRANSFER_SELECTOR
+        refuse("the call is selector 0x#{selector}, not #{TRANSFER_SIGNATURE} (0x#{TRANSFER_SELECTOR})")
+      end
+      want_len = 8 + (2 * WORD_HEX)
+      refuse("calldata is #{raw.length} hex chars, too short for #{TRANSFER_SIGNATURE}") if raw.length < want_len
+
+      recipient = raw[8, WORD_HEX]
+      want_recipient = address.downcase.delete_prefix("0x").rjust(WORD_HEX, "0")
+      unless recipient == want_recipient
+        refuse("the transfer pays 0x#{recipient[-40..]} but the payout destination is #{address}")
+      end
+      got_units = raw[8 + WORD_HEX, WORD_HEX].to_i(16)
+      refuse("the transfer moves #{got_units} base units but the payout is for #{units}") unless got_units == units
+      return if raw.length == want_len
+
+      refuse("calldata carries #{(raw.length - want_len) / 2} trailing bytes after #{TRANSFER_SIGNATURE}")
+    end
+
+    private_class_method :check_header, :check_call
+
+    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
+
+    def self.address?(value)
+      TxVerify.address?(value)
+    end
+
+    def self.same_address?(left, right)
+      address?(left) && address?(right) && left.casecmp(right).zero?
+    end
+
+    private_class_method :refuse, :symbolize, :blank?, :decimal?, :address?, :same_address?
+  end
+end

data/lib/rail0/request.rb

@@ -143,6 +143,7 @@ module Rail0
     end
 
     def page_meta(response)
+      links = page_links(response["link"])
       {
         page:        response["x-page"].to_i,
         per_page:    response["x-per-page"].to_i,
@@ -150,10 +151,27 @@ module Rail0
         # Zero for an empty collection: "no pages" is what there are, so a pager
         # rendered off this renders none. (rail0-gateway#242)
         total_pages: response["x-total-pages"].to_i,
-        links:       page_links(response["link"])
+        links:       links,
+        next_cursor: next_cursor(response["x-next-cursor"], links[:next])
       }.freeze
     end
 
+    # The cursor of the next page on a cursor-paged list (the +after:+ of payments.list
+    # and payouts.list): the x-next-cursor header, or — should a proxy have dropped it —
+    # the +after+ query parameter of the Link +next+. nil on the last page, and on an
+    # offset-paged response (whose +next+ carries +page=+, not +after=+).
+    def next_cursor(header, next_link)
+      cursor = header.to_s.strip
+      return cursor unless cursor.empty?
+      return nil if next_link.nil?
+
+      query = next_link.split("?", 2)[1]
+      return nil if query.nil?
+
+      value = URI.decode_www_form(query).assoc("after")&.last
+      value.nil? || value.empty? ? nil : value
+    end
+
     # RFC 8288 Link into { first:, prev:, next:, last: }. `first`/`last` are always
     # sent, `prev`/`next` only where they exist, and the header is ABSENT entirely on
     # an empty collection — so an empty hash here means "no pages", not "unparsed".

data/lib/rail0/resources/auth.rb

@@ -58,7 +58,7 @@ module Rail0
       #
       # +admin+ is true only for an account holding the operator (administrators)
       # grant: the gateway adds the field on an admin's session alone, and it is
-      # normalised here to a boolean so a standard login reads false rather than nil.
+      # normalized here to a boolean so a standard login reads false rather than nil.
       # Visibility only — every gated route re-checks the grant per request.
       def verify(message:, signature:)
         session = http.post("/auth", { message: message, signature: signature })

data/lib/rail0/resources/chains.rb

@@ -18,7 +18,9 @@ module Rail0
       # List active blockchains supported by RAIL0.
       # @param network_type [String, nil] Filter by "testnet" or "mainnet".
       # @param symbol [String, nil] Filter by native symbol (case-insensitive, e.g. "ETH").
-      # @return [Array<Hash>] chain_id, name, native_symbol, network_type, explorer_url,
+      # @return [Array<Hash>] chain_id, slug (shared by a chain's testnet and mainnet, e.g.
+      #   "arc"; unique per network_type), name, native_symbol, network_type, explorer_url,
+      #   public_rpc_urls (keyless RPC endpoints published for clients),
       #   required_confirmations, finality_tag (the settlement rule: the tag where the
       #   chain serves one, the count only where it does not), and contract — the chain's
       #   active RAIL0 deployment as `{ address:, version:, deployed_at: }` (what holds
@@ -32,6 +34,54 @@ module Rail0
       def list(network_type: nil, symbol: nil)
         http.get("/blockchains#{build_query(network_type: network_type, symbol: symbol)}")
       end
+
+      # Picks one chain out of a {list} result by numeric chain id OR slug. No request.
+      #
+      # +ref+ is an Integer or an all-digit String (a chain id: "5042002", 5042002) or a
+      # slug, compared case-insensitively ("Arc"). A slug is shared by a chain's testnet
+      # and mainnet, so when the list holds both it is AMBIGUOUS and raises rather than
+      # guessing which network the caller meant: pass the chain id, or a list filtered
+      # with +network_type:+. Nothing matching raises too, naming the slugs available.
+      #
+      #   chains = client.chains.list(network_type: "testnet")
+      #   Rail0::Resources::Chains.resolve(chains, "arc")    # => { chain_id: 5042002, slug: "arc", ... }
+      #   Rail0::Resources::Chains.resolve(chains, 5042002)  # the same chain
+      #
+      # @param chains [Array<Hash>] blockchains, as {list} returns them (symbol or string keys)
+      # @param ref [Integer, String] chain id or slug
+      # @return [Hash] the matching chain
+      # @raise [ArgumentError] when nothing matches, or the slug matches several chains
+      def self.resolve(chains, ref)
+        key = ref.to_s.strip
+        raise ArgumentError, "a chain id or slug is required" if key.empty?
+
+        rows = Array(chains).map { |c| c.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k } }
+        return resolve_id(rows, key) if key.match?(/\A\d+\z/)
+
+        matches = rows.select { |c| c[:slug].to_s.casecmp(key).zero? }
+        return matches.first if matches.size == 1
+
+        if matches.empty?
+          raise ArgumentError, "no chain with slug #{key.inspect} (available slugs: #{describe_available(rows)})"
+        end
+
+        ids = matches.map { |c| "#{c[:chain_id]} (#{c[:network_type] || 'unknown network'})" }.join(", ")
+        raise ArgumentError, "slug #{key.inspect} is ambiguous: it matches chains #{ids} — pass the chain id, " \
+                             "or list with network_type:"
+      end
+
+      def self.resolve_id(rows, key)
+        found = rows.find { |c| c[:chain_id].to_s == key.sub(/\A0+(?=\d)/, "") }
+        return found if found
+
+        raise ArgumentError, "no chain with id #{key} (available: #{describe_available(rows)})"
+      end
+
+      def self.describe_available(rows)
+        slugs = rows.map { |c| c[:slug].to_s.downcase }.reject(&:empty?).uniq.sort
+        slugs.empty? ? "none" : slugs.join(", ")
+      end
+      private_class_method :resolve_id, :describe_available
     end
   end
 end