rail0-sdk 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f10297affa2fe993f9f4777ba2c6994610de8a6e2abe54d19b790cabfb09681
-  data.tar.gz: 75ea2a7fdcc4b18cd8b4d62c689bb9a2b0bcb2030793e24a12224ee205275490
+  metadata.gz: 1304e38f4530a6bfdbfe8f3196ed562b4869b9e6ab7d455cae744afb21ad21ed
+  data.tar.gz: 87090219ed6aef2133815ca4a704a5c7a8e926cead00e59688a42aac25f29297
 SHA512:
-  metadata.gz: 211b69279ade20a322f29061a5723ce477e42d6ff50f9f2b2b192569117ffcbc25f35ba32dbe2c56c88ac04501669856cc3f9613ad12a8a2433ba76cf15e4a62
-  data.tar.gz: 1e856d8c347d5793915bdbbceec990cc0bcc12f9e85977e293bc268fee9c4985d19cf114559199a9c88f58850b5e6f83e4e94d5d7e82f69f38036592d284be1e
+  metadata.gz: 77f22e52615cd7cac1b1535084a388111e20850e01a89a39628322bf825f8ea023c1db7e9d185bbb9c0616fa1827add2ebbdb2d8749cbf60fbfe099f6f0719f8
+  data.tar.gz: ae3d34f5cceffb1ea59f33114b53c5308eb115b929bfa581717e7e3357fedbb38a527ef0a35136943eadbc4fa0e93a589ebbacff4f13c880f885c95869644a4a

data/README.md

@@ -127,12 +127,17 @@ client.payments.submit_by_hash(rail0_id, "capture", { transaction_hash: "0x…"
 | `charge_prepare` + `charge` | payee | One-shot authorize + capture; no escrow window |
 | `capture_prepare` + `capture` | payee | Move escrowed funds to the merchant (partial supported) |
 | `void_prepare` + `void` | payee | Cancel the hold, return funds to the payer (only before any capture) |
-| `release_prepare` + `release` | anyone | Return uncaptured escrow to the payer |
+| `release_prepare` + `release` | payer or payee | Return uncaptured escrow to the payer |
 | `refund_prepare` (phase 1+2) + `refund` | payee | Return captured funds to the payer via EIP-3009 |
 | `dispute_prepare` + `dispute` | payer | Open a dispute (signal-only) |
 | `close_dispute_prepare` + `close_dispute` | payer | Close an open dispute |
 | `dispute_submit_by_hash` / `close_dispute_submit_by_hash` | payer | Report a dispute tx the wallet already broadcast |
 
+`release` is the one merchant-side operation either participant may send: the contract
+accepts only the payer or the payee as its sender, and anyone else is refused with 422
+`release_submitter_not_a_party`. `release_prepare(id, from: "0x…")` builds the transaction
+for that sender; omitted, `from` is the signed-in caller.
+
 **Payment statuses:** `unsigned`, `signed`, `authorized`, `charged`, `captured`,
 `partially_captured`, `voided`, `released`, `refunded`, `expired` — plus
 `partially_refunded`, which is no longer produced (a partial refund deliberately leaves
@@ -142,6 +147,13 @@ exhaustive `case` that raises on it.
 `expired` is a never-captured authorization whose window lapsed. It is **not** terminal:
 the escrow is still on-chain and `release` still works from it (closing the payment as
 `released`), so treating it as closed leaves the buyer's funds where they are.
+
+How a `release` settles depends on the balances it leaves, not on the order operations
+arrived in: a total release from `authorized` or `expired` closes the payment as
+`released`; a release that leaves **both** `capturable_amount` and `refundable_amount` at
+zero (say capture 40 → refund 40 → release 60) closes it as `refunded`; any other release
+returns the escrow but leaves the status unchanged, so a captured residual stays
+refundable and disputable.
 **Transaction statuses:** `pending`, `submitting`, `submitted`, `confirmed`, `failed`.
 
 ## Authentication (SIWE)
@@ -156,9 +168,9 @@ Two role rules are worth knowing before the first call, because both surface as
 403 rather than a validation error:
 
 - `payments.create` requires the caller to **be the payer** (`payer_must_be_caller`);
-- the merchant operations (authorize, capture, charge, void, refund) are
-  **payee-only**, while `release` and the prepare steps accept either participant,
-  and `dispute`/`close_dispute` submits are **payer-only**.
+- the merchant operations (authorize, capture, charge, void, refund) and their prepare
+  steps are **payee-only**; `release` — prepare and submit — is the one that accepts
+  either participant; and `dispute`/`close_dispute` submits are **payer-only**.
 
 A wallet that signs *and broadcasts* in one step (MetaMask) reports the result by hash
 instead of handing over a signed transaction: `submit_by_hash` covers the merchant
@@ -225,12 +237,34 @@ logging — it says exactly which sessions died, which `revoked_all: true` canno
 ## Catalog (public)
 
 ```ruby
-client.chains.list                                    # GET /blockchains (each chain's :contract is the active RAIL0 deployment)
+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")
-client.tokens.list                                    # GET /tokens
+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'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 →
+confirmation over the trailing `window_days`, in whole seconds rounded up. It is always
+present, but the percentiles are `nil` below the gateway's minimum sample (20), so size a
+polling deadline from it with a fixed fallback:
+
+```ruby
+FALLBACK = 15 * 60 # seconds
+chain    = client.chains.list.find { |c| c[:chain_id] == 84532 }
+p90      = chain.dig(:settlement, :p90_seconds)
+deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + (p90 ? [3 * p90, FALLBACK].max : FALLBACK)
+```
+
+It is a trailing-window measurement (a capacity figure, cached by the gateway for 10
+minutes), not a promise, so treat it as a hint and never as a timeout that fails a payment.
+
+`tokens.list` without `active:` is the **historical** catalogue — a payment references its
+token forever, so a retired one must still resolve. A checkout picker should pass
+`active: true`: `payments.create` answers 422 `unknown_token` for a retired token.
+
 ## Health
 
 ```ruby
@@ -241,6 +275,9 @@ client.health.get   # GET /health → { status:, api_version:, contract_version:
 
 Paginated calls return `{ data:, meta: }`. `meta` is `{ page:, per_page:, total:, total_pages:, links: }`.
 
+`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.
+
 `total_pages` is **zero** for an empty collection — "no pages" is what there are, so a pager rendered off it renders none. `links` comes from the `Link` header: `:first` and `:last` are always present, `:prev` and `:next` only where they exist, and the hash is empty when the collection is. The URIs are **relative** (path + query) and resolve against the URL you requested — the gateway emits them that way so they cannot advertise the wrong scheme through a TLS-terminating proxy.
 
 ```ruby
@@ -278,6 +315,8 @@ account id first. `id_or_address` accepts the wallet UUID or its 0x address.
 ```ruby
 client.wallets.list(account_id, chain_id: 84532, active: true)
 # => { data: [ { id:, address:, label:, active:, tokens: [...] } ], meta: { page:, per_page:, total: } }
+# chain_id / token_symbol / default / token_active narrow the NESTED holdings, never the wallets.
+client.wallets.list(account_id, token_active: true)
 
 client.wallets.get(account_id, id_or_address)
 client.wallets.update(account_id, id_or_address, label: "Renamed", active: false)
@@ -299,13 +338,14 @@ client.wallets.create(account_id, address: "0x…", **proof, label: "Treasury")
 ```
 
 The proof is **purpose-bound**, and a login proof will not do — the gateway pins
-each endpoint to one statement and refuses the other with 422
+each endpoint to one statement and refuses the others with 422
 `siwe_purpose_mismatch`:
 
 | Endpoint | Statement | Constant |
 |---|---|---|
 | `POST /auth` | `Sign in to RAIL0` | `Rail0::Resources::Auth::LOGIN_STATEMENT` |
 | `POST /accounts/:id/wallets` | `Add this wallet to your RAIL0 account` | `Rail0::Resources::Auth::WALLET_LINK_STATEMENT` |
+| `POST /auth/revoke_all` | `Sign out of RAIL0 everywhere` | `Rail0::Resources::Auth::REVOKE_ALL_STATEMENT` |
 
 That is a security boundary rather than a label: a login signature is handed out
 on every sign-in, so a wallet-link endpoint that accepted one would let anyone
@@ -326,6 +366,11 @@ re-enables it and answers 200 instead of creating a second row. The id passed to
 the other three is the **token's** UUID (`token_id` on the holding), not an id of the
 holding row and not the token address — the gateway looks the holding up by (wallet, token).
 
+The wallet's active **default** holding cannot be disabled or removed — that would leave it
+with no preferred payment method — and the gateway answers 422 `default_payment_method`.
+Make another token the default first (`add_token(..., default: true)` demotes the old one
+in the same transaction), then disable or remove it.
+
 ## Payments
 
 ```ruby
@@ -334,7 +379,11 @@ client.payments.create(params, idempotency_key: nil)  # or keyword fields
 # "idempotency_key_reused" (422) instead of returning the first payment.
 client.payments.get(id)
 client.payments.list(status: "authorized", disputed: false, chain_id: 84532, sort: "-created_at")
+client.payments.list(status: %w[authorized expired])  # any of several states → ?status=authorized,expired
+client.payments.list(operation: "refund")            # payments with at least one refund transaction
 client.payments.transactions(id, operation: "capture")
+client.payments.transactions(id, status: %w[submitting submitted])  # on its way to the chain
+# `operation` on both takes Payments::TRANSACTION_OPERATIONS — dispute and close_dispute included.
 client.payments.redrive(id, transaction_id)           # re-enqueue a stuck broadcast
 # Offer `redrive` on the row's `redrivable` flag — the same predicate the gateway guards
 # the route with — and not on `status == "pending"`: a pending row holding no signed
@@ -357,10 +406,29 @@ client.disputes.list(status: "closed", sort: "-opened_at")
 `payments.list`/`transactions`/`disputes` and `disputes.list` return a paginated
 `{ data:, meta: { page:, per_page:, total: } }` envelope.
 
-Every payment row carries `chain_id`, list rows included. You need it to display
-an amount: `amount` is in base units and the token's decimals resolve from
-`token` **plus** its chain — an address alone identifies a token only within one
-chain — so a listing never needs a `get(id)` per row to render totals.
+`status:` on `payments.list` and `payments.transactions` takes one value or an Array; an
+Array is sent comma-separated and matches **any** of the listed states. An empty Array is
+dropped like `nil` (no filter). An unknown value raises `Rail0::ApiError` 400
+`validation_failed`, naming it. Any query filter given an Array is sent the same way.
+
+Every payment row carries `chain_id` and `decimals`, list rows included (and the payment
+embedded in `disputes.list`). Amounts (`amount`, `capturable_amount`, `refundable_amount`)
+are in base units: divide by `10**decimals` to render them, with no `tokens.list` join and no
+`get(id)` per row. `decimals` is `nil` only when the gateway cannot resolve the token (a
+contract it has not loaded, a token deleted outright). Fall back to `tokens.list` then,
+matching on `token` **plus** `chain_id`, since an address alone identifies a token only
+within one chain.
+
+```ruby
+BigDecimal(row[:amount]) / (10**row[:decimals])  # "100000000", 6 → 100.0
+```
+
+Every payment row also carries `in_flight`: `true` while one of its transactions is on its
+way to the chain, meaning `submitting`, `submitted`, or `pending` holding its signed
+transaction (the `redrivable` rows). A `pending` row still waiting for its signature does not
+count, nor do `confirmed`/`failed` rows. While it is true the balances are about to move, so
+disable further actions on the payment. It comes on list rows too, which embed no
+transactions, so a bulk action can skip busy rows without a `get(id)` each.
 
 ### Refund (two-phase EIP-3009)
 
@@ -377,6 +445,8 @@ client.payments.refund(rail0_id, { signed_transaction: raw })
 
 ### Disputes (payer-driven)
 
+> **Operations go through the gateway.** The gateway mirrors only the operations it prepared. A dispute, close-dispute, capture, void, refund or release sent to the RAIL0 contract directly — outside this SDK's prepare/submit calls — happens on-chain, but the payment's status and balances on the gateway do not change and no webhook is sent; a merchant is not told about a dispute its buyer opened that way. The gateway records it for its operators as a sync error (`external_operation`).
+
 Disputes are signed on-chain by the payer and follow the same prepare → submit
 pattern. Like the rest of `/payments` they need a session, but the payer's
 account-less SIWE login is enough:
@@ -424,10 +494,37 @@ client.webhooks.enable(id)
 client.webhooks.disable(id)
 client.webhooks.rotate_secret(id)    # returns a fresh shared_secret
 client.webhooks.reset_circuit(id)
-client.webhooks.event_callbacks(id, status: "failed")
+# status is "delivered" or "failed" only; payment_id takes a UUID or a rail0_id.
+client.webhooks.event_callbacks(id, status: "failed", response_code: "500")
+client.webhooks.redeliver(id, callback_id)  # 202 { status: "queued" } — replay one delivery
 client.webhooks.delete(id)           # 204
 ```
 
+Every delivery's `payment` object carries `capturable_amount` (base units) and
+`authorization_expiry` (epoch seconds), whatever the topic. That is what makes
+`payments.authorization_expiring` actionable. The gateway sends it **once per payment**, a
+configurable notice (24h by default) before `authorization_expiry`, for a payment that can
+still be captured (`authorized`, `partially_captured`, `partially_refunded`) and still holds
+escrow. It is the last chance to capture; `payments.expired` says the chance has gone. Its
+`transaction` is `null`, and the time left is `authorization_expiry` minus the event's
+`emitted_at` (ISO-8601). There is no separate field for it because it would be stale on
+every retry:
+
+```ruby
+event = JSON.parse(raw, symbolize_names: true)
+if event[:topic] == "payments.authorization_expiring"
+  payment   = event[:payment]
+  secs_left = payment[:authorization_expiry] - Time.iso8601(event[:emitted_at]).to_i
+  # capture payment[:capturable_amount] (base units) within secs_left, or let it expire
+end
+```
+
+`redeliver` replays a recorded delivery's exact payload — the same event id, so a receiver
+that already processed it deduplicates — under a fresh signature. It is the way back for
+events lost while the circuit breaker was open. Delivery is async and the dispatcher drops
+anything for an inactive webhook, so `enable` (if disabled) or `reset_circuit` (if the
+breaker opened) **first**, or the 202 is answered and the replay silently dropped.
+
 ### Verifying a delivery
 
 Every delivery carries `X-Rail0-Topic`, `X-Rail0-Timestamp` and
@@ -469,9 +566,19 @@ digest with it. Comparison is constant-time.
 client.accounts.get(account_id)
 # => { id: "019f…", name: "Test Merchant", email: "merchant@rail0.test",
 #      created_at: "2026-08-01T00:00:00Z", updated_at: "2026-08-20T00:00:00Z" }
+
+# Update the same profile — only the fields passed are sent.
+client.accounts.update(account_id, email: "ops@merchant.example")
+client.accounts.update(account_id, name: "Merchant Ltd", email: "ops@merchant.example")
 ```
 
 `email` is in the response because the holder is this endpoint's only possible caller.
+
+`update` needs at least one of `name`/`email` (it raises `ArgumentError` before sending an
+empty PATCH, which the gateway would answer with 400). Both are unique across accounts, so
+a value another account holds answers **409**. It is a write on the account, so a
+deactivated wallet (403 `wallet_deactivated`) or account (403 `account_deactivated`) cannot
+make it. The gateway's `active` field is operator-only and not exposed here.
 The account's wallets are a collection under the same path (`client.wallets`), and
 buyer-facing discovery is `client.payment_methods`.
 
@@ -542,9 +649,17 @@ client.analytics.breakdown(by: "operation")
 # => [{ key: "capture", orders: 1, transactions: 2 }, …]
 ```
 
-All three take the same filters — `mode`, `status`, `token`, `chain_id`, `from`, `to` — so
-the same question can be asked at three resolutions: one total, a series over time, a split
-by dimension. `from`/`to` filter the payment's CREATION date, which matters when reading
+All three take the same filters — `mode`, `status`, `token`, `chain_id`, `from`, `to`,
+`payee` — so the same question can be asked at three resolutions: one total, a series over
+time, a split by dimension. Figures cover all of the account's wallets unless `payee` pins
+one of them (a 0x address the account owns — another address is refused with 403, a
+malformed one with 400):
+
+```ruby
+client.analytics.summary(payee: "0xYourWallet…")
+```
+
+`from`/`to` filter the payment's CREATION date, which matters when reading
 gas: a payment created in one period and captured in the next books its capture gas in the
 first.
 
@@ -634,8 +749,7 @@ end
 ```
 
 **`error` is the only field to branch on.** It is the specific condition, read from the
-gateway's `code` and falling back to the older `error` sub-code and then to `status` (the
-wider family), so an older gateway still yields the most specific value it sent.
+gateway's `code`.
 
 `title` and `detail` come from the gateway's error catalogue, so the same condition always
 reads the same way whichever endpoint surfaced it; `detail` is written to be shown to a
@@ -674,8 +788,8 @@ Rail0::Client.new(
 ### Rate limits
 
 The gateway throttles two surfaces independently: the public, unauthenticated one **per
-IP** (100 requests / 60s by default — SIWE nonce + verify, `/payment_methods`, the
-catalog reads, `/health`) and everything authenticated **per session**, keyed on the
+IP** (100 requests / 60s by default — SIWE nonce + verify, `/auth/revoke_all`,
+`/payment_methods`, the catalog reads, `/health`) and everything authenticated **per session**, keyed on the
 JWT's subject (300 / 60s). Over budget it answers **429** with `code: "rate_limited"` and
 a `Retry-After`.
 
@@ -691,8 +805,8 @@ rescue Rail0::ApiError => e
 end
 ```
 
-Note what the number means: the gateway sends **the whole throttle period**, not the time
-left in the current window, so it is an upper bound on the wait rather than a measurement.
+Note what the number means: the gateway sends **the time left in the current window**
+(the same value as `RateLimit-Reset`), not the window's length, so it is the wait itself.
 
 `retry_on_429: true` makes the SDK do that waiting for you — Retry-After, clamped to
 `retry_after_cap`, plus a little jitter (see `Rail0::Backoff`; callers sharing one session
@@ -737,7 +851,7 @@ lib/rail0/
     wallets.rb         account-scoped wallet management (JWT)
     payments.rb        payment lifecycle + disputes
     disputes.rb        account-level dispute listing (JWT)
-    accounts.rb        the caller's own account profile (JWT)
+    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)
     query.rb           shared query-string helper
@@ -765,6 +879,26 @@ uses them everywhere, table-aligned hashes because some literals are tables, and
 (`retry_on_429`, `eip712`, `secp256k1`) that each spell themselves their own way. A linter
 that argues with the codebase teaches people to ignore it.
 
+## Publishing
+
+Releases publish from GitHub Actions (`.github/workflows/release.yml`) through RubyGems
+**Trusted Publishing**: RubyGems.org trusts that workflow in this repo, so there is no API
+key to store or rotate and no OTP prompt.
+
+1. Merge a PR that bumps `Rail0::VERSION` in `lib/rail0/version.rb`.
+2. Publish a GitHub release on `main` tagged `v<version>` (e.g. `v1.2.0`).
+
+The workflow checks the tag against `Rail0::VERSION`, runs `rake build` (rubocop and the
+specs first, then the gem) and pushes it. A version already on RubyGems.org is skipped, so
+a re-run (Actions → release → Run workflow, from `main`, with the tag as input) is always
+safe — that is also how a release cut before the workflow existed gets published.
+
+One-time setup, by an owner of the gem on rubygems.org: rail0-sdk → Trusted publishers →
+GitHub Actions, repository `commercelayer/rail0-ruby`, workflow `release.yml`.
+
+Publishing by hand still works as a fallback (`gem build rail0-sdk.gemspec && gem push
+rail0-sdk-<version>.gem`, with the OTP the gem's `rubygems_mfa_required` asks for).
+
 ## License
 
 [MIT](LICENSE)

data/lib/rail0/api_error.rb

@@ -21,9 +21,10 @@ module Rail0
     #     otherwise. Surfaced because the alternative is a caller guessing: the SDK used
     #     to drop the header, so "rate limited" arrived with no idea of for how long.
     #
-    #     Note it is the WHOLE window the gateway throttles over, not the time left in it
-    #     — the limiter sends its period verbatim — so it is an upper bound on the wait,
-    #     not a measurement. Rail0::Backoff clamps it for that reason.
+    #     It is the time LEFT in the current throttle window, not the window's length:
+    #     the limiter buckets by wall clock, so the gateway computes the remainder exactly
+    #     (the same number it sends as RateLimit-Reset). Rail0::Backoff still clamps it,
+    #     against a hostile or misconfigured value from anything in between.
     attr_reader :status, :error, :title, :detail, :retry_after
 
     # @param status [Integer]

data/lib/rail0/backoff.rb

@@ -24,11 +24,10 @@ module Rail0
   #    per-session bucket and would all be told the same Retry-After, wake together, and
   #    recreate the burst the limiter just rejected.
   #
-  # 2. THE CAP IS NOT PARANOIA. The gateway sends the WHOLE period as Retry-After
-  #    (rack_attack.rb: `headers["retry-after"] = match_data[:period].to_s`), not the time
-  #    remaining in the window — so hitting the limit one second in is told to wait the
-  #    full 60. Capping bounds both that over-wait and a hostile or misconfigured value
-  #    from anything between the client and the gateway.
+  # 2. THE CAP IS NOT PARANOIA. The gateway sends the time LEFT in the throttle window as
+  #    Retry-After (it used to send the whole period, which over-waited by up to a full
+  #    window). Even an exact number comes through whatever sits between the client and
+  #    the gateway, so capping bounds a hostile or misconfigured value.
   module Backoff
     module_function
 

data/lib/rail0/error_hints.rb

@@ -51,6 +51,11 @@ module Rail0
     "not_payee" => "only the merchant (payee) may do this",
     "not_payer" => "only the buyer (payer) may do this",
     "not_payer_or_payee" => "only the payer or the payee may do this",
+    "release_submitter_not_a_party" => "a release must be sent by the payment's payer or payee — omit `from` to build it for the signed-in wallet",
+    "payer_must_be_caller" => "the payer must be the signed-in wallet — sign in as the buyer to create its payment",
+    "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — reactivate it or sign in with another of the account's wallets",
+    "account_deactivated" => "the merchant account is deactivated: void, release and refund still work, but authorize, charge, capture and account changes do not — ask an operator to reactivate it",
+    "not_redrivable" => "only a pending transaction that already holds its signed bytes can be redriven — check the transaction's `redrivable` flag, and submit the signature if it has none",
     "refund_expired" => "the refund window has closed (refundExpiry passed) — refund/dispute is no longer possible",
     "authorization_not_expired" => "release opens only after authorizationExpiry — wait until it passes",
     "already_captured" => "already (partially) captured — use release for the remainder, not void",
@@ -63,9 +68,10 @@ module Rail0
     "no_active_contract" => "no active RAIL0 contract on that chain",
     "missing_param" => "a required parameter is missing from the request",
     # 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, not_your_account)
-    # because they need different fixes. This entry kept describing one of them long
-    # after the split — and the rule it named no longer exists in the gateway at all.
+    # their own (not_the_payee, not_the_payer, wallet_deactivated, account_deactivated,
+    # not_your_account) because they need different fixes. This entry kept describing
+    # one of them long after the split — and the rule it named no longer exists in the
+    # gateway at all.
     "forbidden" => "not permitted for this session — typically the operator grant, a resource owned by another account, or a transaction signed by the wrong wallet"
   }.freeze
 

data/lib/rail0/http_client.rb

@@ -17,8 +17,8 @@ module Rail0
     #   It does NOT need `max_retries` to be set as well. That pairing is a footgun —
     #   the flag would silently do nothing — so on its own it allows one retry.
     # @param retry_after_cap [Numeric] longest wait to honour, in seconds. The gateway
-    #   sends its whole throttle period as Retry-After rather than the time left in it,
-    #   so this bounds both the over-wait and any hostile value from in between.
+    #   sends the time left in its throttle window as Retry-After; this bounds any
+    #   hostile or misconfigured value from in between.
     def initialize(base_url:, headers: {}, token: nil, timeout: 30, logger: nil,
                    max_retries: 0, retry_delay: 0.2, retry_on_429: false,
                    retry_after_cap: 60)

data/lib/rail0/resources/accounts.rb

@@ -4,12 +4,14 @@ module Rail0
   module Resources
     # The merchant account itself (requires JWT).
     #
-    # One method, and that is the whole surface by design: the gateway guards
-    # `/accounts/:account_id` with an ownership check — a JWT whose account matches the
-    # path — so a caller can only ever read its OWN account. There is no endpoint for
-    # reading another merchant's, and an id that is not an account answers 404 exactly as
-    # another account's id does, so the pair cannot be used to learn whether an account
-    # exists.
+    # Read and update. The gateway guards `/accounts/:account_id` with an
+    # owner-or-operator check: a merchant session reaches only its OWN account, and an
+    # operator (an admin session) may reach any. For anyone else another account's id
+    # answers the same 403 `not_your_account` as a plain ownership miss, so the pair
+    # cannot be used to learn whether an account exists.
+    #
+    # The gateway's PATCH also takes `active`, but that field is the OPERATOR's (an owner
+    # sending it gets 403), so it is deliberately not exposed here.
     #
     # The account's wallets are a collection under the same path and live on
     # {Resources::Wallets}; buyer-facing discovery of what a merchant accepts lives on
@@ -25,11 +27,36 @@ module Rail0
       # The account's own profile.
       # @param account_id [String] The account UUID — must be the one this JWT belongs to.
       # @return [Hash] `id`, `name`, `email`, `created_at`, `updated_at`. `email` is part of
-      #   the response because the holder is this endpoint's only possible caller: it is a
-      #   merchant reading its own contact address, never another's.
+      #   the response because only the account's owner, or an operator, can read it.
       def get(account_id)
         http.get("/accounts/#{account_id}")
       end
+
+      # Update the account's own profile (PATCH /accounts/:account_id).
+      #
+      # Only the fields passed are sent, and at least one is required: a PATCH with
+      # nothing to change is a caller bug, which the gateway answers with 400 — so this
+      # raises ArgumentError first rather than spending a request on it. Both fields are
+      # UNIQUE across accounts, so a value another account already holds answers 409.
+      #
+      # This is a write on the account itself, so a deactivated wallet (403
+      # wallet_deactivated) or a deactivated account (403 account_deactivated) cannot
+      # make it: a revoked key must not be able to redirect the contact address where
+      # the merchant's operational notifications go.
+      #
+      # @param account_id [String] The account UUID — must be the one this JWT belongs to.
+      # @param name [String, nil] New display name (non-blank; unique across accounts).
+      # @param email [String, nil] New contact email (non-blank; unique across accounts).
+      # @return [Hash] the updated profile, same shape as {get}.
+      # @raise [ArgumentError] when neither name nor email is given.
+      def update(account_id, name: nil, email: nil)
+        body = {}
+        body[:name]  = name  unless name.nil?
+        body[:email] = email unless email.nil?
+        raise ArgumentError, "at least one of name or email is required" if body.empty?
+
+        http.patch("/accounts/#{account_id}", body)
+      end
     end
   end
 end

data/lib/rail0/resources/analytics.rb

@@ -16,13 +16,15 @@ module Rail0
     # chain: it is denominated in the chain's native token, so it is reported per chain and
     # never totalled.
     #
+    # Figures cover every wallet of the account unless `payee` pins one of them.
+    #
     # These methods return the parsed JSON as-is, so the keys documented below are the
     # contract this SDK offers — there is no typed wrapper standing between them and the
     # gateway.
     class Analytics
       include Query
 
-      FILTERS = %i[mode status token chain_id from to].freeze
+      FILTERS = %i[mode status token chain_id from to payee].freeze
 
       attr_reader :http
 
@@ -38,6 +40,10 @@ module Rail0
       # @param chain_id [Integer, nil] Chain ID. Pass nil or 0 for all chains.
       # @param from [String, nil] ISO-8601 — payments created at/after this time.
       # @param to [String, nil] ISO-8601 — payments created at/before this time.
+      # @param payee [String, nil] One of the account's wallet addresses (0x…) — scopes the
+      #   figures to that wallet instead of all the account's wallets. The gateway refuses an
+      #   address the account does not own (403) and a malformed one (400). Accepted by all
+      #   three views.
       # @return [Hash] the headline KPIs:
       #   * `orders`, `disputed` — counts.
       #   * `refund_rate`, `dispute_rate` — fractions in [0,1], per ORDER.
@@ -95,7 +101,7 @@ module Rail0
       #   often the operation ran — a partial capture runs several times on one order — and
       #   `orders` is how many orders it touched.
       def breakdown(by:, **filters)
-        raise ArgumentError, "by is required (token, chain, mode or status)" if by.nil? || by.to_s.empty?
+        raise ArgumentError, "by is required (token, chain, mode, status or operation)" if by.nil? || by.to_s.empty?
 
         http.get("/analytics/breakdown#{build_query(**only_filters(filters), by: by)}")
       end

data/lib/rail0/resources/chains.rb

@@ -20,7 +20,15 @@ module Rail0
       # @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,
       #   required_confirmations, finality_tag (the settlement rule: the tag where the
-      #   chain serves one, the count only where it does not)
+      #   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
+      #   the money; nullable in principle, present in practice), and settlement — how long
+      #   an operation on the chain has taken to confirm ON THIS GATEWAY, as
+      #   `{ p50_seconds:, p90_seconds:, sample_size:, window_days: }`: broadcast-to-confirmation
+      #   percentiles (whole seconds, rounded up) over the trailing `window_days`. Always
+      #   present; the percentiles are nil below the gateway's minimum sample (20), so check
+      #   `sample_size` and keep a fixed fallback. A wait-deadline hint (e.g. 3 × p90_seconds,
+      #   floored at your fallback), not a guarantee.
       def list(network_type: nil, symbol: nil)
         http.get("/blockchains#{build_query(network_type: network_type, symbol: symbol)}")
       end

data/lib/rail0/resources/disputes.rb

@@ -23,7 +23,7 @@ module Rail0
       # List the account's disputes.
       # @param status [String, nil] Filter by "open" or "closed".
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def list(status: nil, sort: nil, page: nil, per_page: nil)

data/lib/rail0/resources/payments.rb

@@ -18,6 +18,11 @@ module Rail0
       # Operations accepted by the prepare/submit endpoints.
       OPERATIONS = %w[authorize capture charge void release refund].freeze
 
+      # Every operation a transaction row can carry — a superset of {OPERATIONS}, since
+      # dispute/close_dispute have routes of their own. The values the `operation`
+      # filters on {list} and {transactions} accept.
+      TRANSACTION_OPERATIONS = (OPERATIONS + %w[dispute close_dispute]).freeze
+
       attr_reader :http
 
       def initialize(http)
@@ -27,7 +32,9 @@ module Rail0
 
       # List payments for the authenticated wallet (requires JWT). Returns
       # payments where the caller is the payer or payee.
-      # @param status [String, nil] Filter by payment status.
+      # @param status [String, Array<String>, nil] Filter by payment status: one state, or
+      #   an Array matching ANY of them (sent comma-separated, `status=authorized,expired`).
+      #   An unknown value is 400 `validation_failed` naming it.
       # @param mode [String, nil] Filter by mode ("authorize" or "charge").
       # @param payer [String, nil] Filter by payer address.
       # @param payee [String, nil] Filter by payee address.
@@ -35,6 +42,8 @@ module Rail0
       # @param rail0_id [String, nil] Filter by the logical on-chain payment id (0x…).
       # @param chain_id [Integer, nil] Filter by the payment's chain.
       # @param disputed [Boolean, nil] Filter by whether an open dispute exists.
+      # @param operation [String, nil] Only payments carrying at least one transaction with
+      #   this operation (see {TRANSACTION_OPERATIONS}).
       # @param min_amount [String, nil] Minimum amount in token BASE UNITS (inclusive).
       # @param max_amount [String, nil] Maximum amount in token BASE UNITS (inclusive).
       #   These two really are base units — the filter runs against the stored column.
@@ -43,14 +52,20 @@ module Rail0
       # @param created_from [String, nil] Only payments created at/after this ISO-8601 time.
       # @param created_to [String, nil] Only payments created at/before this ISO-8601 time.
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
-      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
+      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }. Each row
+      #   carries, besides the payment fields, `chain_id`, `decimals` (Integer, or nil when
+      #   the gateway can't resolve the token — fall back to {Tokens#list} then) to render the
+      #   base-unit amounts without a token lookup, and `in_flight` (Boolean: a transaction is
+      #   `submitting`, `submitted`, or `pending` holding its signed transaction — disable
+      #   further actions on the row while true).
       def list(status: nil, mode: nil, payer: nil, payee: nil, token: nil, rail0_id: nil,
-               chain_id: nil, disputed: nil, min_amount: nil, max_amount: nil,
+               chain_id: nil, disputed: nil, operation: nil, min_amount: nil, max_amount: nil,
                created_from: nil, created_to: nil, sort: nil, page: nil, per_page: nil)
         query = build_query(status: status, mode: mode, payer: payer, payee: payee, token: token,
                             rail0_id: rail0_id, chain_id: chain_id, disputed: disputed,
+                            operation: operation,
                             min_amount: min_amount, max_amount: max_amount,
                             created_from: created_from, created_to: created_to,
                             sort: sort, page: page, per_page: per_page)
@@ -80,17 +95,21 @@ module Rail0
 
       # Fetch current payment state (DB status + live on-chain amounts + transactions).
       # @param id [String] Payment UUID or rail0_id.
-      # @return [Hash]
+      # @return [Hash] The payment with its embedded transactions, including `decimals`
+      #   (Integer or nil — divide `amount`, `capturable_amount` and `refundable_amount` by
+      #   10**decimals to render them) and `in_flight` (Boolean — see {list}).
       def get(id)
         http.get("/payments/#{id}")
       end
 
       # List on-chain transactions for a payment.
       # @param id [String] Payment UUID or rail0_id.
-      # @param operation [String, nil] Filter by operation (see {OPERATIONS}).
-      # @param status [String, nil] Filter by transaction status.
+      # @param operation [String, nil] Filter by operation (see {TRANSACTION_OPERATIONS} —
+      #   dispute and close_dispute included).
+      # @param status [String, Array<String>, nil] Filter by transaction status: one, or an
+      #   Array matching any of them (`%w[submitting submitted]` = on its way to the chain).
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def transactions(id, operation: nil, status: nil, sort: nil, page: nil, per_page: nil)
@@ -149,7 +168,7 @@ module Rail0
       # @param id [String] Payment UUID or rail0_id.
       # @param status [String, nil] Filter by dispute status ("open" or "closed").
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def disputes(id, status: nil, sort: nil, page: nil, per_page: nil)
@@ -239,9 +258,10 @@ module Rail0
         submit(id, "void", params)
       end
 
-      # Phase 1 — build the unsigned release() transaction. +from+ overrides the
-      # submitter address (defaults to the payer). Returns uncaptured escrow to the
-      # payer.
+      # Phase 1 — build the unsigned release() transaction for +from+, whose nonce it
+      # carries. +from+ must be the payment's payer or payee (the gateway answers 422
+      # release_submitter_not_a_party otherwise); omitted, it is the signed-in caller.
+      # Returns uncaptured escrow to the payer.
       def release_prepare(id, from: nil, idempotency_key: nil)
         prepare(id, "release", from ? { from: from } : {}, idempotency_key: idempotency_key)
       end

data/lib/rail0/resources/query.rb

@@ -10,10 +10,30 @@ module Rail0
     module Query
       private
 
+      # Builds "?k=v&…" from keyword filters, or "" when every value is nil.
+      #
+      # An Array value becomes ONE comma-separated pair (`status: %w[a b]` →
+      # `status=a,b`): the gateway's multi-value filters (e.g. `status` on
+      # GET /payments, #367) take the comma form. Each element is escaped on its
+      # own and the separating comma is left literal, so a comma can never leak
+      # in from an element. nil elements are dropped; an Array left empty drops
+      # the whole pair, the same as nil, rather than sending a blank `status=`
+      # the gateway would reject with 400.
       def build_query(**params)
-        pairs = params.compact.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }
+        pairs = params.filter_map do |k, v|
+          value = query_value(v)
+          "#{k}=#{value}" unless value.nil?
+        end
         pairs.empty? ? "" : "?#{pairs.join('&')}"
       end
+
+      def query_value(value)
+        return nil if value.nil?
+        return CGI.escape(value.to_s) unless value.is_a?(Array)
+
+        items = value.compact
+        items.map { |item| CGI.escape(item.to_s) }.join(",") unless items.empty?
+      end
     end
   end
 end

data/lib/rail0/resources/tokens.rb

@@ -15,13 +15,20 @@ module Rail0
         freeze
       end
 
-      # List active tokens, optionally filtered by chain and/or symbol.
+      # List tokens, optionally filtered by chain, symbol and/or active flag.
+      #
+      # Without `active:` this is the HISTORICAL catalogue — retired tokens included — so
+      # a payment created long ago still resolves its token. Only an active token may be
+      # used for a NEW payment (POST /payments answers 422 unknown_token otherwise), so a
+      # checkout picker should pass `active: true`.
+      #
       # @param chain_id [Integer, nil] Chain ID to filter by. Pass nil or 0 for all chains.
       # @param symbol [String, nil] Filter by token symbol (case-insensitive, e.g. "USDC").
-      # @return [Array<Hash>] chain_id, symbol, address, decimals
-      def list(chain_id: nil, symbol: nil)
+      # @param active [Boolean, nil] Filter by active flag; omitted returns every token.
+      # @return [Array<Hash>] chain_id, symbol, address, decimals, active
+      def list(chain_id: nil, symbol: nil, active: nil)
         chain_id = nil if chain_id == 0
-        http.get("/tokens#{build_query(chain_id: chain_id, symbol: symbol)}")
+        http.get("/tokens#{build_query(chain_id: chain_id, symbol: symbol, active: active)}")
       end
     end
   end

data/lib/rail0/resources/wallets.rb

@@ -27,14 +27,17 @@ module Rail0
       # @param token_symbol [String, nil] Restrict nested tokens to this symbol (e.g. "USDC").
       # @param active [Boolean, nil] Filter wallets by active flag.
       # @param default [Boolean, nil] Restrict nested holdings to the default one.
+      # @param token_active [Boolean, nil] Restrict nested holdings to this active status
+      #   (does not hide wallets). Omitted returns holdings whatever their flag.
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def list(account_id, chain_id: nil, token_symbol: nil, active: nil, default: nil,
-               sort: nil, page: nil, per_page: nil)
+               token_active: nil, sort: nil, page: nil, per_page: nil)
         query = build_query(chain_id: chain_id, token_symbol: token_symbol, active: active,
-                            default: default, sort: sort, page: page, per_page: per_page)
+                            default: default, token_active: token_active,
+                            sort: sort, page: page, per_page: per_page)
         http.get_list("/accounts/#{account_id}/wallets#{query}")
       end
 
@@ -140,6 +143,11 @@ module Rail0
       # not the token's contract address. The gateway looks the holding up by
       # (wallet, token_id); the same applies to {enable_token} and {disable_token}.
       #
+      # The wallet's active DEFAULT holding cannot be removed: that would leave it with no
+      # preferred payment method and nothing saying so, and the gateway answers 422
+      # default_payment_method. Make another token the default first ({add_token} with
+      # `default: true` demotes this one in the same transaction), then remove it.
+      #
       # @return [nil]
       def remove_token(account_id, id_or_address, token_id)
         http.delete("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}")
@@ -153,6 +161,9 @@ module Rail0
 
       # Disable an existing token holding without forgetting it — the holding (and
       # its default flag) survives, so re-enabling restores the previous setup.
+      #
+      # Like {remove_token}, refused with 422 default_payment_method for the wallet's
+      # active default holding — promote another token to default first.
       # @return [Hash] the token holding
       def disable_token(account_id, id_or_address, token_id)
         http.patch("/accounts/#{account_id}/wallets/#{id_or_address}/tokens/#{token_id}/disable")

data/lib/rail0/resources/webhooks.rb

@@ -25,6 +25,7 @@ module Rail0
         payments.voided
         payments.released
         payments.refunded
+        payments.authorization_expiring
         payments.expired
         payments.failed
         payments.disputed
@@ -45,7 +46,7 @@ module Rail0
       # @param active [Boolean, nil] Filter by active flag.
       # @param circuit_state [String, nil] Filter by circuit state ("closed" or "open").
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
       def list(topic: nil, active: nil, circuit_state: nil, sort: nil, page: nil, per_page: nil)
@@ -119,22 +120,50 @@ module Rail0
 
       # List delivery attempts for a webhook.
       # @param id [String] Webhook UUID.
-      # @param status [String, nil] Filter by delivery status ("pending", "delivered", "failed").
+      # @param status [String, nil] Filter by delivery status: "delivered" or "failed" only
+      #   (anything else, "pending" included, is a 400).
       # @param topic [String, nil] Filter by event topic.
-      # @param payment_id [String, nil] Filter by the payment the delivery is for.
+      # @param payment_id [String, nil] Filter by the payment the delivery is for: its UUID
+      #   or its rail0_id (0x…). One that names no payment matches nothing rather than erroring.
+      # @param response_code [String, Integer, nil] Filter by the subscriber's exact HTTP
+      #   response code (e.g. 500) — `status: "failed"` finds the failures, this says which.
       # @param since [String, nil] Only deliveries at/after this ISO-8601 time.
       # @param until_time [String, nil] Only deliveries at/before this ISO-8601 time (query key: "until").
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
-      # @param page [Integer, nil] Page number (1-based).
+      # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }
-      def event_callbacks(id, status: nil, topic: nil, payment_id: nil, since: nil,
-                          until_time: nil, sort: nil, page: nil, per_page: nil)
-        query = build_query(status: status, topic: topic, payment_id: payment_id, since: since,
-                            until: until_time, sort: sort, page: page, per_page: per_page)
+      def event_callbacks(id, status: nil, topic: nil, payment_id: nil, response_code: nil,
+                          since: nil, until_time: nil, sort: nil, page: nil, per_page: nil)
+        query = build_query(status: status, topic: topic, payment_id: payment_id,
+                            response_code: response_code, since: since, until: until_time,
+                            sort: sort, page: page, per_page: per_page)
         http.get_list("/webhooks/#{id}/event_callbacks#{query}")
       end
 
+      # Re-deliver one recorded delivery's exact payload
+      # (POST /webhooks/:id/event_callbacks/:callback_id/redeliver).
+      #
+      # The recovery lever for events lost while the circuit breaker was open: the
+      # gateway stores each delivery's payload and replays THAT payload verbatim — the
+      # same embedded event id, so a receiver that already processed it deduplicates —
+      # under a fresh timestamped signature.
+      #
+      # Delivery is ASYNC (the standard dispatcher: same SSRF checks, retries and circuit
+      # accounting), and the dispatcher drops a delivery for a webhook that is not active.
+      # So re-activate the webhook FIRST — {enable} if it was disabled, {reset_circuit} if
+      # the breaker opened — or the 202 below is answered and the replay silently dropped.
+      #
+      # A callback id that is malformed, unknown, belongs to another webhook, or was
+      # recorded before payloads were stored all answer 404.
+      #
+      # @param id [String] Webhook UUID.
+      # @param callback_id [String] The event callback's UUID (from {event_callbacks}).
+      # @return [Hash] `{ status: "queued" }` (HTTP 202).
+      def redeliver(id, callback_id)
+        http.post("/webhooks/#{id}/event_callbacks/#{callback_id}/redeliver", {})
+      end
+
       # Delete a webhook. Returns HTTP 204.
       # @param id [String] Webhook UUID.
       # @return [nil]

data/lib/rail0/types.rb

@@ -133,6 +133,22 @@ module Rail0
       :required_confirmations,  # Integer — Confirmations this gateway waits for before treating a transaction as settled. The FALLBACK rule: where the chain serves a finality tag (see finality_tag) that tag governs instead, so a client showing this number on such a chain is describing a rule that is not in force.
       :finality_tag,            # String — The block tag the chain calls settled (`safe`, `finalized`), when it serves one — and what the gateway actually gates on. Null where the chain serves none, in which case required_confirmations is counted.
       :contract,                # ChainContract
+      :settlement,              # BlockchainSettlement
+      keyword_init: true
+    )
+
+    # How long an operation on this chain has taken to settle ON THIS GATEWAY: percentiles of broadcast
+    # (`submitted_at`) to confirmation (`confirmed_at`) over the confirmed transactions of the trailing
+    # `window_days`. End-to-end — the chain's finality lag plus the gateway/indexer pipeline — so it is
+    # what a client actually waits for, not the chain's finality. A measurement, not a guarantee: use it
+    # as a wait-deadline hint (e.g. a small multiple of `p90_seconds`) and keep a fixed fallback for
+    # when it is null. Deliberately a long-window capacity figure, not a live alarm (#289). Always
+    # present; the percentiles are null when `sample_size` is below the gateway's minimum (20).
+    BlockchainSettlement = Struct.new(
+      :p50_seconds,  # Integer — Median settlement time, whole seconds rounded up. Null below the minimum sample.
+      :p90_seconds,  # Integer — 90th-percentile settlement time, whole seconds rounded up — the figure to size a deadline from. Null below the minimum sample.
+      :sample_size,  # Integer — Confirmed transactions measured in the window (0 when none).
+      :window_days,  # Integer — The trailing window the figures cover, in days.
       keyword_init: true
     )
 
@@ -188,7 +204,8 @@ module Rail0
       keyword_init: true
     )
 
-    # Base persisted payment fields, plus the `chain_id` of the payment's deployment.
+    # Base persisted payment fields, plus the `chain_id` of the payment's deployment, its token's
+    # `decimals`, and whether a transaction is `in_flight`.
     Payment = Struct.new(
       :id,                    # String
       :contract_id,           # String
@@ -203,11 +220,13 @@ module Rail0
       :payer,                 # String
       :payee,                 # String
       :token,                 # String
+      :decimals,              # Decimals of the payment's token: divide `amount`, `capturable_amount` and `refundable_amount` (base units) by 10^decimals to render them, with no GET /tokens join on `token` + `chain_id`. Resolved from the gateway's in-memory chain catalogue, retired tokens and archived contract versions included. Null only when the gateway cannot resolve the token (a contract it has not loaded, a token deleted outright) — fall back to GET /tokens then.
       :authorization_expiry,  # Integer
       :refund_expiry,         # Integer
       :escrow_stranded,       # Boolean — True exactly inside the stranded-escrow window (#233): a partial capture has permanently ruled void out, and release only opens at authorization_expiry — so no verb can return the buyer's uncaptured escrow until then. Mirrors RAIL0.sol; the gateway names the window, it cannot shorten it.
       :escrow_returnable_at,  # String — When the stranded escrow becomes returnable (release opens) — the authorization expiry as ISO-8601. Null whenever nothing is stranded, so presence alone is the signal.
       :disputed,              # Boolean — True while an open dispute exists.
+      :in_flight,             # Boolean — True while one of the payment's transactions is on its way to the chain and not yet settled: status `submitting`, `submitted`, or `pending` holding its signed transaction (the `redrivable` rows — signed and handed over, broadcast not yet sent). A `pending` row still awaiting its signature (an unfinished prepare) does not count, nor do `confirmed`/`failed`. While true the mirrored balances are about to move, so a client should disable further actions on the payment. Carried by list rows too, which embed no transactions; computed for a whole page in one query.
       :last_error_code,       # Decoded reason of the last failed on-chain attempt; null once the payment makes forward progress. Non-null means the latest attempt failed.
       :last_error_message,    # Human-readable form of last_error_code.
       :description,
@@ -324,6 +343,7 @@ module Rail0
       :operation,         # String — Same vocabulary as `Transaction.operation` — dispute rows go stale too.
       :payment_id,        # String — Protocol-level rail0_id.
       :chain_id,          # Integer
+      :contract_address,  # String — Address (lowercase) of the RAIL0 deployment the payment is bound to, archived versions included. The sweeper accepts a receipt's event only when this contract emitted it.
       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.1.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-24 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Ruby SDK for the RAIL0 stablecoin payment protocol