rail0-sdk 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60c25c2843d57ee49df3b17267e56a612f56701d61e48430786b1c6435987eb9
-  data.tar.gz: d8ef2d01d59b1a775f116753608bba6ab90d0d868a360040c0bc8fdc64f64de0
+  metadata.gz: 1304e38f4530a6bfdbfe8f3196ed562b4869b9e6ab7d455cae744afb21ad21ed
+  data.tar.gz: 87090219ed6aef2133815ca4a704a5c7a8e926cead00e59688a42aac25f29297
 SHA512:
-  metadata.gz: e7e6441337f7daf05f4e55ba22d94a380755f5775fd203b0699e8f16029fc493c88e9863a81e2d1559e71c383db7b79330503cd724c2219dd0a1b169badfac81
-  data.tar.gz: 943a28ce8740139e30e4966ce1021b9a85271789418a2274d505a6457733a09e8cc84c3c8f435ff34962dec3ed7e5beded3fc0f7cec131de626d8e5d6535fc5d
+  metadata.gz: 77f22e52615cd7cac1b1535084a388111e20850e01a89a39628322bf825f8ea023c1db7e9d185bbb9c0616fa1827add2ebbdb2d8749cbf60fbfe099f6f0719f8
+  data.tar.gz: ae3d34f5cceffb1ea59f33114b53c5308eb115b929bfa581717e7e3357fedbb38a527ef0a35136943eadbc4fa0e93a589ebbacff4f13c880f885c95869644a4a

data/README.md

@@ -237,13 +237,30 @@ 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 — 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.
@@ -362,8 +379,10 @@ 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
@@ -387,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)
 
@@ -462,6 +500,25 @@ client.webhooks.redeliver(id, callback_id)  # 202 { status: "queued" } — repla
 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

data/lib/rail0/resources/chains.rb

@@ -22,7 +22,13 @@ module Rail0
       #   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
-      #   the money; nullable in principle, present in practice)
+      #   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/payments.rb

@@ -32,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.
@@ -52,7 +54,12 @@ module Rail0
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
       # @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, operation: nil, min_amount: nil, max_amount: nil,
                created_from: nil, created_to: nil, sort: nil, page: nil, per_page: nil)
@@ -88,7 +95,9 @@ 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
@@ -97,7 +106,8 @@ module Rail0
       # @param id [String] Payment UUID or rail0_id.
       # @param operation [String, nil] Filter by operation (see {TRANSACTION_OPERATIONS} —
       #   dispute and close_dispute included).
-      # @param status [String, nil] Filter by transaction status.
+      # @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; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).

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/webhooks.rb

@@ -25,6 +25,7 @@ module Rail0
         payments.voided
         payments.released
         payments.refunded
+        payments.authorization_expiring
         payments.expired
         payments.failed
         payments.disputed

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,

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.2.0"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Commerce Layer