rail0-sdk 1.3.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23d06a854473333eb6779af7bcec4ea5d370ab9c24106cef8a1db9809ca29803
-  data.tar.gz: b6a28727e25233378a5c39feceb00f7a638d44590a8f9f01f356e1e6e0d35f91
+  metadata.gz: 06dc80b9fc301df5fb28259087c18ceae341e047418d6c26855a17fc2076c0e8
+  data.tar.gz: ee45ee4241b861c2443af42dc3453a824e1d5974c3accb872f0d03b9356959d3
 SHA512:
-  metadata.gz: fdb399b1895e43ef062221da06357db402bb59fc746a36d6a21499d9ac82625723db5dc454cb8c46cb1e77e4889d05b00f8497da9d858a0e8f470e286c29f4a4
-  data.tar.gz: 7f329e33476a42b6d3304c3a1978dab10425740a460d2f6a066660ce9f67e24399c81d783372d65172b5247e670362970f82ddbf16e7fb7d5c7a5172e8fb9e8b
+  metadata.gz: 4a41a60e24ca27221b91e4c35021636cd8f5b134810369354f653b947f9578124c666c09005cc13f25b0f121262d06ff209f97bc637fcf20f2ea8fab5e616c0a
+  data.tar.gz: 3459c91f1e3ed2b9a2c3ede420e004d63c44d2fdf0def948b49e781d7b7f6b4bf00ac7e2c92c5d5b141c46704245c4aed6daed2f5c560199a39f1ed9b7137c24

data/README.md

@@ -129,8 +129,8 @@ client.payments.submit_by_hash(rail0_id, "capture", { transaction_hash: "0x…"
 | `void_prepare` + `void` | payee | Cancel the hold, return funds to the payer (only before any capture) |
 | `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_prepare(id, reason: nil)` + `dispute` | payer | Open a dispute (signal-only; reason optional) |
+| `close_dispute_prepare(id, reason: nil)` + `close_dispute` | payer | Close an open dispute (reason optional) |
 | `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
@@ -324,6 +324,12 @@ client.wallets.delete(account_id, id_or_address)                    # 204
 client.wallets.balances(account_id, id_or_address, chain_id: 84532) # live on-chain balances
 ```
 
+`delete` only deactivates (the same as `update(active: false)`; payments name the
+address, so the row stays). Either way the account's **only active wallet** is
+refused with 422 `last_active_wallet` — login resolves the account from a wallet,
+so an account with none could neither act nor add one back. Add or reactivate
+another wallet first.
+
 **Registering a wallet needs a SIWE proof-of-ownership of the address being
 added**, not merely the session JWT. `auth.prove_address` runs that handshake and
 returns the `message` + `signature` to splat into `create`. Sign with **the added
@@ -366,10 +372,12 @@ 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.
+While the wallet accepts other tokens, its 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. The **last** active holding can be disabled even as the default: the wallet
+then accepts nothing, and the next holding enabled becomes the default.
 
 ## Payments
 
@@ -378,13 +386,23 @@ client.payments.create(params, idempotency_key: nil)  # or keyword fields
 # Reusing a key for DIFFERENT terms raises Rail0::ApiError with code
 # "idempotency_key_reused" (422) instead of returning the first payment.
 client.payments.get(id)
+client.payments.update(id, description: "Order #42")  # → the payment, same shape as get
+client.payments.update(id, description: nil)          # nil (or "") clears it
+# The description is the only editable field: off-chain, so any status, settled included.
+# Payer or payee only (a non-participant gets 404); over 255 characters is a 422.
 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
+# The operator's cross-account list (admin only, 403 otherwise): every payment on the
+# gateway, same filters, plus three that exist only there — the payee account, whether a
+# last_error_code is set, and authorized payments whose hold lapses within N SECONDS.
+client.payments.list(scope: "all", has_error: true)
+client.payments.list(scope: "all", expiring_within: 24 * 3600)
+client.payments.list(scope: "all", account_id: "019f…")
 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
+client.payments.redrive(id, transaction_id)           # re-enqueue a stuck broadcast (payee, or an operator)
 # 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
 # transaction is not redrivable, and there the next step is submitting the signature, not
@@ -452,14 +470,56 @@ pattern. Like the rest of `/payments` they need a session, but the payer's
 account-less SIWE login is enough:
 
 ```ruby
-prep = client.payments.dispute_prepare(rail0_id, reason: "0x…") # reason optional
+prep = client.payments.dispute_prepare(rail0_id, reason: "not_received") # reason optional
 raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], BUYER_PRIVATE_KEY)
 client.payments.dispute(rail0_id, { signed_transaction: raw })
 # … later …
-client.payments.close_dispute_prepare(rail0_id)
+prep = client.payments.close_dispute_prepare(rail0_id, reason: "withdrawn") # or omit reason:
+raw  = Rail0::Signing.sign_transaction(prep[:unsigned_transaction], BUYER_PRIVATE_KEY)
 client.payments.close_dispute(rail0_id, { signed_transaction: raw })
 ```
 
+#### Dispute reasons
+
+`reason:` is **optional** on both prepares. Omit it (or pass `nil` or a blank string) and
+the SDK leaves `reason` out of the request: the dispute is opened/closed with no reason,
+the calldata carries the zero bytes32 (the gateway also accepts the zero word explicitly),
+and it reads back as `No reason given`. When given, it is a code from the gateway's
+dispute-reason dictionary (a String or a Symbol) or exactly that code's bytes32,
+`keccak256("rail0.dispute.<code>")`, which is what the contract stores. Anything else — any
+other non-zero bytes32, a code from the other list, or the system-only `full_refund` — is
+refused 422 `unknown_dispute_reason`.
+
+| Kind | Codes |
+|------|-------|
+| Open (`dispute_prepare`) | `not_received`, `not_as_described`, `damaged_or_defective`, `duplicate`, `incorrect_amount`, `cancelled`, `refund_not_received`, `unauthorized`, `other` |
+| Close (`close_dispute_prepare`) | `resolved_with_merchant`, `withdrawn`, `item_received`, `other` |
+| System (never sent; read back only) | `full_refund` — a full refund auto-closed the dispute |
+
+`Rail0::DisputeReasons` carries the dictionary as constants, generated from the gateway's
+`DisputeOpenReason` / `DisputeCloseReason` / `DisputeSystemCloseReason` schemas:
+
+```ruby
+Rail0::DisputeReasons::OPEN                        # [Reason(code:, description:, bytes32:), …]
+Rail0::DisputeReasons.codes(:close)                # ["resolved_with_merchant", "withdrawn", …]
+Rail0::DisputeReasons.find(:open, "not_received")  # Reason, or nil (also by bytes32)
+Rail0::DisputeReasons.valid?(:close, "full_refund") # false: system-only
+Rail0::DisputeReasons.valid?(:open, nil)           # true: no reason is accepted
+Rail0::DisputeReasons.none?(Rail0::DisputeReasons::ZERO_BYTES32) # true: nil, blank or zero
+Rail0::DisputeReasons.description_for(:open, "0x00…00") # "No reason given" (the zero word)
+Rail0::DisputeReasons.description_for(:open, "0x12…34") # "Unrecognised reason"
+```
+
+Lookups take a kind because the lists overlap: `other` is both an open and a close reason.
+
+A dispute read back (`payments.disputes`, `disputes.list`) carries the decoded reason next
+to the raw bytes32: `reason_code` / `reason_description`, and `close_reason_code` /
+`close_reason_description` once closed (`close_reason_code` may be `full_refund`). A
+dispute with no reason (the zero bytes32) has `reason_code: nil` and
+`reason_description: "No reason given"`; a non-zero bytes32 outside the dictionary — a
+dispute opened on the contract directly — is kept verbatim in `reason`, with
+`reason_code: nil` and `reason_description: "Unrecognised reason"`.
+
 ### Generic prepare/submit
 
 Every wrapper delegates to the generic form, useful for dynamic operations:
@@ -556,6 +616,25 @@ window is what bounds a replay of a captured delivery. Pass the body exactly as
 received: re-serialising a parsed hash changes key order and whitespace, and the
 digest with it. Comparison is constant-time.
 
+**Rotating the secret without a gap.** After `rotate_secret` the gateway keeps the
+replaced key for a grace window (`WEBHOOK_SECRET_GRACE`, one hour by default): inside it
+every delivery carries `X-Rail0-Signature` under the new key **and**
+`X-Rail0-Signature-Previous` under the old one, so an endpoint verifies with whichever key
+it has deployed and nothing in flight at rotation becomes unverifiable. Deploy the new
+secret at your pace within the window; an endpoint that still holds the old one verifies
+the previous header instead — the old key signs only, and is never honoured past the
+window. A second rotation inside it drops the oldest key.
+
+```ruby
+verify = ->(signature) do
+  Rail0::WebhookSignature.verify(body: raw, signature: signature,
+                                 timestamp: request.headers["X-Rail0-Timestamp"],
+                                 secret: ENV.fetch("RAIL0_WEBHOOK_SECRET"))
+end
+ok = verify.call(request.headers["X-Rail0-Signature"]) ||
+     verify.call(request.headers["X-Rail0-Signature-Previous"])
+```
+
 ## Account (JWT)
 
 ```ruby
@@ -564,21 +643,28 @@ digest with it. Comparison is constant-time.
 # merchant's account — and an id that is not an account answers 404 exactly as
 # another account's id does, so the pair says nothing about existence.
 client.accounts.get(account_id)
-# => { id: "019f…", name: "Test Merchant", email: "merchant@rail0.test",
+# => { id: "019f…", name: "Test Merchant", email: "merchant@rail0.test", priority_tip: true,
 #      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")
+client.accounts.update(account_id, priority_tip: false)   # minimum tip on the account's own transactions
 ```
 
 `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.
+`update` needs at least one of `name`/`email`/`priority_tip` (it raises `ArgumentError`
+before sending an empty PATCH, which the gateway would answer with 400). Name and email 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.
+
+**`priority_tip`** is the fee setting of the account's **own** transactions (authorize,
+capture, void, release, refund): `true`, the default, tips the network's suggested priority
+fee; `false` uses the chain's minimum tip (0 on most chains, 25 gwei on Polygon PoS/Amoy) —
+cheaper, slower to confirm under load. The buyer's dispute/close-dispute never read it.
 The account's wallets are a collection under the same path (`client.wallets`), and
 buyer-facing discovery is `client.payment_methods`.
 
@@ -838,7 +924,7 @@ broadcast may already be in flight.
 ## Project structure
 
 ```text
-gen/generate.rb        regenerates lib/rail0/types.rb from the gateway OpenAPI schema
+gen/generate.rb        regenerates lib/rail0/types.rb and lib/rail0/dispute_reasons.rb from the gateway OpenAPI schema
 
 lib/rail0/
   client.rb            Rail0::Client — entry point
@@ -851,6 +937,7 @@ lib/rail0/
   webhook_signature.rb Rail0::WebhookSignature — delivery verification
   signing.rb           EIP-3009 + EIP-1559 signing (requires 'eth')
   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)
   version.rb           Rail0::VERSION
   resources/
@@ -878,7 +965,7 @@ bundle exec rubocop      # style only
 bundle exec rubocop -a   # and fix what is safely fixable
 bundle exec rspec        # specs only
 
-# Regenerate lib/rail0/types.rb after a gateway schema change:
+# Regenerate lib/rail0/types.rb and lib/rail0/dispute_reasons.rb after a gateway schema change:
 #   defaults to ../rail0-gateway/docs/openapi.json, or set RAIL0_SCHEMA_PATH.
 ruby gen/generate.rb
 ```

data/lib/rail0/dispute_reasons.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# Code generated by gen/generate.rb — DO NOT EDIT.
+# Re-run `ruby gen/generate.rb` after updating the gateway OpenAPI schema.
+#
+# Source: rail0-gateway/docs/openapi.json — components.schemas.DisputeOpenReason,
+# DisputeCloseReason and DisputeSystemCloseReason (enum, x-enum-descriptions and
+# x-enum-bytes32, aligned by index).
+
+module Rail0
+  # The gateway's dispute-reason dictionary. On-chain a dispute reason is a bytes32,
+  # keccak256("rail0.dispute.<code>"); the dispute prepares take either the code or
+  # exactly that bytes32, and refuse anything else 422 unknown_dispute_reason. A
+  # dispute read back carries `reason_code`/`reason_description` (and the close_
+  # counterparts) already decoded by the gateway; these constants are for building a
+  # picker, validating input before a round trip, or decoding a raw bytes32.
+  module DisputeReasons
+    # One dictionary entry: the code the API speaks, its English description and the
+    # bytes32 the contract stores.
+    Reason = Struct.new(:code, :description, :bytes32, keyword_init: true)
+
+    # What the gateway reports as the description of a bytes32 outside the dictionary.
+    UNRECOGNISED_DESCRIPTION = "Unrecognised reason"
+
+    # What the gateway reports as the description of a dispute opened or closed with no
+    # reason — the zero bytes32 on-chain (rail0-gateway#382).
+    NO_REASON_DESCRIPTION = "No reason given"
+
+    # The all-zero bytes32: what the contract stores when no reason is given.
+    ZERO_BYTES32 = "0x0000000000000000000000000000000000000000000000000000000000000000"
+
+    # Reasons a payer may open a dispute with (Payments#dispute_prepare).
+    OPEN = [
+      Reason.new(
+        code: "not_received",
+        description: "Goods or service not received",
+        bytes32: "0x8b8e446d6f906b670526e73bf5502f1db64b2150c42360febf9dec0d075a28f9"
+      ).freeze,
+      Reason.new(
+        code: "not_as_described",
+        description: "Not as described, or not what was ordered",
+        bytes32: "0xd7ac93eb8a6f78f2398d7131c7d34ac3cc667872ccd86f9acb2acf0b1c1ce68d"
+      ).freeze,
+      Reason.new(
+        code: "damaged_or_defective",
+        description: "Arrived damaged or defective",
+        bytes32: "0xedaf2417cca94f10d7611552c2c3a9a9fcf7aeecb58bc213c9290ea0c7e58f3a"
+      ).freeze,
+      Reason.new(
+        code: "duplicate",
+        description: "Charged twice for the same purchase",
+        bytes32: "0x21d2ae9aec01aa72dfe968be0b24b311d8f9b26491ad3f5122ee6bce9c0da16f"
+      ).freeze,
+      Reason.new(
+        code: "incorrect_amount",
+        description: "Amount differs from what was agreed",
+        bytes32: "0x668fab4989c1fca438fa96c57778b3a0f1a46766bfbce495d8704fd1b0aa6ab6"
+      ).freeze,
+      Reason.new(
+        code: "cancelled",
+        description: "Order or subscription cancelled but still charged",
+        bytes32: "0xf0e563be58fdee0107cd6907d4040a859af4753a93cafa838e374a1b6c6880d4"
+      ).freeze,
+      Reason.new(
+        code: "refund_not_received",
+        description: "A refund promised by the merchant never arrived",
+        bytes32: "0x654f13ad1cef4e3e1c74161e98f531e730883aa4d14855ee35546f5485de13ce"
+      ).freeze,
+      Reason.new(
+        code: "unauthorized",
+        description: "Payment not recognised (e.g. a compromised wallet)",
+        bytes32: "0x5a8e87ece389352e3ad16b9cc84ecb7348115546c041e079f18011d158934079"
+      ).freeze,
+      Reason.new(
+        code: "other",
+        description: "Other reason, detailed off-chain",
+        bytes32: "0x0c507c226b608fa1f2920608f9c8baf135357fe717c6cd9ac355ae6451b63667"
+      ).freeze
+    ].freeze
+
+    # Reasons a payer may close a dispute with (Payments#close_dispute_prepare).
+    CLOSE = [
+      Reason.new(
+        code: "resolved_with_merchant",
+        description: "Resolved with the merchant off-chain",
+        bytes32: "0x37b092a939a58d27e17848d569e5abb446933c05d90edb8f2ad69caae8b9416a"
+      ).freeze,
+      Reason.new(
+        code: "withdrawn",
+        description: "Withdrawn by the buyer (a mistake, or changed their mind)",
+        bytes32: "0x304c3ad3e1c95131e0e666568cb55d269a5382b83f18dcd07137626b07de4d91"
+      ).freeze,
+      Reason.new(
+        code: "item_received",
+        description: "The disputed goods or service arrived after all",
+        bytes32: "0xafa7760b6eaeb3756917ec71a4add26b6982f123779bbefca4af237ed2a9cbb1"
+      ).freeze,
+      Reason.new(
+        code: "other",
+        description: "Other reason",
+        bytes32: "0x0c507c226b608fa1f2920608f9c8baf135357fe717c6cd9ac355ae6451b63667"
+      ).freeze
+    ].freeze
+
+    # Close reasons the protocol records on its own — read back on a dispute, never accepted from a caller.
+    SYSTEM = [
+      Reason.new(
+        code: "full_refund",
+        description: "Closed automatically by a full refund",
+        bytes32: "0x8d72b2d99f736f70b77d5c4eb77867aa31f7d7be526741b1ba241c1c663b0f6c"
+      ).freeze
+    ].freeze
+
+    # The lists by kind, for the lookups below.
+    KINDS = { open: OPEN, close: CLOSE, system: SYSTEM }.freeze
+
+    # The entries of one kind (:open, :close or :system).
+    # @param kind [Symbol, String]
+    # @return [Array<Reason>]
+    # @raise [ArgumentError] for any other kind.
+    def self.all(kind)
+      KINDS.fetch(kind.to_sym) { raise ArgumentError, "unknown dispute reason kind: #{kind.inspect}" }
+    end
+
+    # The codes of one kind, in dictionary order.
+    # @param kind [Symbol, String]
+    # @return [Array<String>]
+    def self.codes(kind)
+      all(kind).map(&:code)
+    end
+
+    # The entry of +kind+ that +value+ names — a code ("not_received" or :not_received)
+    # or exactly its bytes32 (0x-hex, either case) — or nil. Lookups are per kind
+    # because the lists overlap: "other" is both an open and a close reason, with one
+    # bytes32.
+    # @param kind [Symbol, String]
+    # @param value [String, Symbol, nil]
+    # @return [Reason, nil]
+    def self.find(kind, value)
+      return nil if value.nil?
+
+      needle = value.to_s
+      all(kind).find { |r| r.code == needle || r.bytes32.casecmp?(needle) }
+    end
+
+    # Whether +value+ means "no reason": nil, a blank string, or the zero bytes32. The
+    # reason is optional on both prepares, and the gateway records any of these as the
+    # zero bytes32.
+    # @param value [String, Symbol, nil]
+    # @return [Boolean]
+    def self.none?(value)
+      needle = value.to_s.strip
+      needle.empty? || needle.casecmp?(ZERO_BYTES32)
+    end
+
+    # Whether the dispute prepare of +kind+ (:open or :close) would accept +value+:
+    # no reason at all (see {.none?}), or a code / bytes32 from that list. :system is
+    # never accepted from a caller, so it always answers false.
+    # @param kind [Symbol, String]
+    # @param value [String, Symbol, nil]
+    # @return [Boolean]
+    def self.valid?(kind, value)
+      return false if kind.to_sym == :system
+
+      none?(value) || !find(kind, value).nil?
+    end
+
+    # The description the gateway would give +value+ as a +kind+ reason:
+    # {NO_REASON_DESCRIPTION} for no reason (see {.none?}), the entry's description
+    # when it is in that list, else {UNRECOGNISED_DESCRIPTION}.
+    # @param kind [Symbol, String]
+    # @param value [String, Symbol, nil]
+    # @return [String]
+    def self.description_for(kind, value)
+      return NO_REASON_DESCRIPTION if none?(value)
+
+      find(kind, value)&.description || UNRECOGNISED_DESCRIPTION
+    end
+  end
+end

data/lib/rail0/error_hints.rb

@@ -18,6 +18,7 @@ module Rail0
     "already_disputed" => "a dispute is already open — close it first",
     "not_disputed" => "there is no open dispute to close",
     "nothing_to_dispute" => "a dispute needs a merchant-held (refundable) balance",
+    "unknown_dispute_reason" => "reason must be a dispute-reason code (Rail0::DisputeReasons.codes(:open) / codes(:close)) or exactly its bytes32 — full_refund is system-only",
     "transaction_not_overwritable" => "a transaction for this operation is already in flight — wait for it to settle",
     "signer_mismatch" => "the signing key doesn't match the payment's payer/payee",
     # The SIWE BINDING failures, split out of signer_mismatch so a failed login says
@@ -55,6 +56,10 @@ module Rail0
     "payer_must_be_caller" => "the payer must be the signed-in wallet — sign in as the buyer to create its payment",
     "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — reactivate it or sign in with another of the account's wallets",
     "account_deactivated" => "the merchant account is deactivated: void, release and refund still work, but authorize, charge, capture and account changes do not — ask an operator to reactivate it",
+    # Login resolves the account FROM a wallet, so an account left with no active one
+    # could neither act nor add a wallet back.
+    "last_active_wallet" => "this is the account's only active wallet — add or reactivate another wallet first, then switch this one off",
+    "last_admin" => "the change would leave no active operator — grant the operator role to another active account first",
     "not_redrivable" => "only a pending transaction that already holds its signed bytes can be redriven — check the transaction's `redrivable` flag, and submit the signature if it has none",
     "refund_expired" => "the refund window has closed (refundExpiry passed) — refund/dispute is no longer possible",
     "authorization_not_expired" => "release opens only after authorizationExpiry — wait until it passes",

data/lib/rail0/resources/accounts.rb

@@ -30,8 +30,12 @@ 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 only the account's owner, or an operator, can read it.
+      # @return [Hash] `id`, `name`, `email`, `priority_tip`, `created_at`, `updated_at`.
+      #   `email` is part of the response because only the account's owner, or an operator,
+      #   can read it. `priority_tip` is the fee setting of the account's OWN transactions
+      #   (authorize, capture, void, release, refund): true, the default, tips the network's
+      #   suggested priority fee; false uses the chain's minimum tip — 0 on most chains,
+      #   25 gwei on Polygon PoS/Amoy. The buyer's dispute/close_dispute never read it.
       def get(account_id)
         http.get("/accounts/#{segment(account_id)}")
       end
@@ -40,8 +44,10 @@ module Rail0
       #
       # 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.
+      # raises ArgumentError first rather than spending a request on it. Name and email
+      # are UNIQUE across accounts, so a value another account already holds answers 409.
+      # `priority_tip: false` is a value, not an absence: it is sent as false and switches
+      # the account's own transactions to the chain's minimum tip; nil leaves it alone.
       #
       # This is a write on the account itself, so a deactivated wallet (403
       # wallet_deactivated) or a deactivated account (403 account_deactivated) cannot
@@ -51,13 +57,17 @@ module Rail0
       # @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).
+      # @param priority_tip [Boolean, nil] Tip the network's suggested priority fee on the
+      #   account's own transactions (true, the gateway default) or the chain's minimum tip
+      #   (false). Owner or admin.
       # @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)
+      # @raise [ArgumentError] when none of name, email or priority_tip is given.
+      def update(account_id, name: nil, email: nil, priority_tip: 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?
+        body[:name]         = name         unless name.nil?
+        body[:email]        = email        unless email.nil?
+        body[:priority_tip] = priority_tip unless priority_tip.nil?
+        raise ArgumentError, "at least one of name, email or priority_tip is required" if body.empty?
 
         http.patch("/accounts/#{segment(account_id)}", body)
       end

data/lib/rail0/resources/payments.rb

@@ -31,7 +31,8 @@ module Rail0
       end
 
       # List payments for the authenticated wallet (requires JWT). Returns
-      # payments where the caller is the payer or payee.
+      # payments where the caller is the payer or payee — or, with `scope: "all"`
+      # (admin only), every payment on the gateway.
       # @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.
@@ -51,6 +52,16 @@ module Rail0
       #   the gateway scales by the token's decimals. The two units coexist in the API.
       # @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 scope [String, nil] "mine" (the default): the authenticated wallet's payments.
+      #   "all": every payment on the gateway — the operator's cross-account list on the
+      #   same call, admin session required (403 otherwise, never silently narrowed to your
+      #   own). The three filters below exist only there and are ignored without it.
+      # @param account_id [String, nil] scope "all" only: payments whose payee is one of
+      #   this account's wallets.
+      # @param has_error [Boolean, nil] scope "all" only: true = payments carrying a
+      #   `last_error_code`, false = none.
+      # @param expiring_within [Integer, nil] scope "all" only: `authorized` payments whose
+      #   `authorization_expiry` falls within this many SECONDS from now (1..90 days).
       # @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).
@@ -62,12 +73,15 @@ module Rail0
       #   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)
+               created_from: nil, created_to: nil, scope: nil, account_id: nil, has_error: nil,
+               expiring_within: 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,
+                            scope: scope, account_id: account_id, has_error: has_error,
+                            expiring_within: expiring_within,
                             sort: sort, page: page, per_page: per_page)
         http.get_list("/payments#{query}")
       end
@@ -102,6 +116,24 @@ module Rail0
         http.get("/payments/#{segment(id)}")
       end
 
+      # Set or clear a payment's description (PATCH /payments/{id}).
+      #
+      # The description is the only field this route edits: it is off-chain metadata, so
+      # it can change at any status, settled payments included. Only a participant (the
+      # payer or the payee) may edit it — a non-participant gets the same 404 as an unknown
+      # id, and a deactivated caller wallet a 403 `wallet_deactivated`.
+      #
+      # +description:+ is required, and is always sent: passing +nil+ sends JSON +null+,
+      # which clears it (as does +""+). Over 255 characters is a 422.
+      # (rail0-gateway#373)
+      #
+      # @param id [String] Payment UUID or rail0_id.
+      # @param description [String, nil] The new description; +nil+ or +""+ clears it.
+      # @return [Hash] The updated payment, the same shape {get} returns.
+      def update(id, description:)
+        http.patch("/payments/#{segment(id)}", { description: description })
+      end
+
       # List on-chain transactions for a payment.
       # @param id [String] Payment UUID or rail0_id.
       # @param operation [String, nil] Filter by operation (see {TRANSACTION_OPERATIONS} —
@@ -147,7 +179,9 @@ module Rail0
       # signature, not retrying a send that never happened.
       #
       # The transaction id is resolved THROUGH the payment, so one belonging to another
-      # payment answers 404 rather than redriving someone else's row.
+      # payment answers 404 rather than redriving someone else's row. Payee-gated, like
+      # the other operation writes — or an operator session on any payment, which the
+      # gateway records in its audit log as transaction.redrive.
       #
       # @param id [String] Payment UUID or rail0_id.
       # @param transaction_id [String] The transaction row to redrive.
@@ -290,8 +324,18 @@ module Rail0
       end
 
       # Phase 1 — build the unsigned dispute() transaction (payer only).
+      #
+      # +reason+ is optional (rail0-gateway#382). Omitted (nil) or blank, it is left
+      # out of the request and the dispute is opened with no reason: the calldata
+      # carries the zero bytes32 (which the gateway also accepts explicitly), read back
+      # as "No reason given". When given it must be a code from
+      # {Rail0::DisputeReasons::OPEN} (e.g. "not_received" or :not_received) or exactly
+      # that code's bytes32; the gateway refuses anything else 422
+      # +unknown_dispute_reason+ — the close/system codes included — so it is the
+      # authority; the SDK sends the value as given rather than second-guessing a
+      # dictionary it may lag behind.
       # @param id [String] Payment UUID or rail0_id.
-      # @param reason [String, nil] Optional bytes32 code (0x…); defaults to zero server-side.
+      # @param reason [String, Symbol, nil] A DisputeOpenReason code, or its bytes32 (0x…); nil for none.
       # @return [Hash]
       def dispute_prepare(id, reason: nil, idempotency_key: nil)
         prepare_dispute("dispute/prepare", id, reason, idempotency_key: idempotency_key)
@@ -306,8 +350,15 @@ module Rail0
       end
 
       # Phase 1 — build the unsigned closeDispute() transaction (payer only).
+      #
+      # +reason+ is optional, as for {#dispute_prepare}: omitted or blank closes with
+      # no reason (the zero bytes32, "No reason given"). When given it must be a code
+      # from {Rail0::DisputeReasons::CLOSE} (e.g. "withdrawn") or exactly that code's
+      # bytes32. +full_refund+ ({Rail0::DisputeReasons::SYSTEM}) is recorded by the
+      # protocol itself and, like any other value, is refused 422
+      # +unknown_dispute_reason+.
       # @param id [String] Payment UUID or rail0_id.
-      # @param reason [String, nil] Optional bytes32 code (0x…).
+      # @param reason [String, Symbol, nil] A DisputeCloseReason code, or its bytes32 (0x…); nil for none.
       # @return [Hash]
       def close_dispute_prepare(id, reason: nil, idempotency_key: nil)
         prepare_dispute("dispute/close/prepare", id, reason, idempotency_key: idempotency_key)
@@ -352,8 +403,11 @@ module Rail0
       # +path+ is one of this class's own literals ("dispute/prepare",
       # "dispute/close/prepare"), never caller input, so it is interpolated as-is:
       # its `/` is meant to separate segments. Only +id+ goes through {#segment}.
+      # A nil or blank +reason+ is left out of the body (no reason); anything else is
+      # sent as given, stripped, for the gateway to resolve.
       def prepare_dispute(path, id, reason, idempotency_key: nil)
-        body = reason ? { reason: reason } : {}
+        value = reason.to_s.strip
+        body = value.empty? ? {} : { reason: value }
         http.post("/payments/#{segment(id)}/#{path}", body,
                   headers: idempotency_headers(idempotency_key))
       end

data/lib/rail0/resources/wallets.rb

@@ -77,7 +77,9 @@ module Rail0
         http.post("/accounts/#{segment(account_id)}/wallets", body)
       end
 
-      # Update a wallet's label and/or active status.
+      # Update a wallet's label and/or active status. +active: false+ on the account's
+      # only active wallet raises ApiError 422 +last_active_wallet+: login resolves the
+      # account from a wallet, so an account with none could neither act nor add one back.
       # @param account_id [String] Account UUID.
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @param label [String, nil] New label.
@@ -90,7 +92,8 @@ module Rail0
         http.patch(wallet_path(account_id, id_or_address), body)
       end
 
-      # Soft-delete (deactivate) a wallet. Returns HTTP 204.
+      # Soft-delete (deactivate) a wallet — the same as +update(active: false)+, so the
+      # account's only active wallet raises ApiError 422 +last_active_wallet+. Returns HTTP 204.
       # @param account_id [String] Account UUID.
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @return [nil]
@@ -143,10 +146,12 @@ 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.
+      # While the wallet accepts other tokens, its 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. The LAST active holding can be removed even as the
+      # default: the wallet then accepts nothing, and the gateway clears the flag with it.
       #
       # @return [nil]
       def remove_token(account_id, id_or_address, token_id)
@@ -159,11 +164,13 @@ module Rail0
         http.patch("#{wallet_path(account_id, id_or_address)}/tokens/#{segment(token_id)}/enable")
       end
 
-      # Disable an existing token holding without forgetting it — the holding (and
-      # its default flag) survives, so re-enabling restores the previous setup.
+      # Disable an existing token holding without forgetting it — the holding survives,
+      # so re-enabling restores it; the first holding enabled on a wallet that accepts
+      # nothing becomes its default again.
       #
       # Like {remove_token}, refused with 422 default_payment_method for the wallet's
-      # active default holding — promote another token to default first.
+      # active default holding while other holdings are active — promote another token to
+      # default first. The last active holding can be disabled, default flag and all.
       # @return [Hash] the token holding
       def disable_token(account_id, id_or_address, token_id)
         http.patch("#{wallet_path(account_id, id_or_address)}/tokens/#{segment(token_id)}/disable")

data/lib/rail0/resources/webhooks.rb

@@ -105,6 +105,15 @@ module Rail0
       end
 
       # Generate a new shared secret, returned once on the response.
+      #
+      # The replaced secret is kept for a grace window (the gateway's
+      # WEBHOOK_SECRET_GRACE, one hour by default): inside it every delivery carries
+      # X-Rail0-Signature under the new key AND X-Rail0-Signature-Previous under the
+      # old one, so an endpoint verifies with whichever key it has deployed and nothing
+      # in flight at rotation becomes unverifiable — see {Rail0::WebhookSignature}. The
+      # old key signs only, is never honoured past the window, and a second rotation
+      # inside it drops the oldest key.
+      #
       # @param id [String] Webhook UUID.
       # @return [Hash] webhook record including the new shared_secret
       def rotate_secret(id)

data/lib/rail0/types.rb

@@ -10,6 +10,17 @@
 
 module Rail0
   module Types
+    # What still names a wallet's address: the payments and transactions an admin is shown before
+    # switching the wallet off.
+    WalletUsage = Struct.new(
+      :wallet_id,               # String
+      :address,                 # String
+      :payments_as_payee,       # Integer
+      :payments_as_payer,       # Integer
+      :transactions_as_sender,  # Integer
+      keyword_init: true
+    )
+
     # A wallet's on-chain balances, one entry per chain.
     WalletBalances = Struct.new(
       :wallet_id,  # String
@@ -75,6 +86,38 @@ module Rail0
       keyword_init: true
     )
 
+    # GET /admin/rpc_health: per-chain RPC reachability as seen from the gateway's process.
+    AdminRpcHealth = Struct.new(
+      :status,      # String — The worst chain status.
+      :checked_at,  # String — When the probe ran; a cached answer keeps its original time.
+      :chains,      # Array
+      keyword_init: true
+    )
+
+    AdminRpcHealthChain = Struct.new(
+      :chain_id,        # Integer
+      :name,            # String
+      :finality_tag,    # String
+      :ok,              # Boolean — At least one endpoint serves the chain.
+      :primary_status,  # String — The first endpoint's status; null when none is configured.
+      :status,          # String — ok: every endpoint up; degraded: some; error: none, or no endpoint configured.
+      :endpoints,       # Array
+      keyword_init: true
+    )
+
+    AdminRpcHealthEndpoint = Struct.new(
+      :url,         # String — Scheme, host, port and path only.
+      :ok,          # Boolean
+      :status,      # String
+      :error,       # String — Short `Class: first line`; never an upstream body.
+      :chain_id,    # Integer — What the node reported.
+      :latency_ms,  # Integer — First round trip, handshake included.
+      :head,        # Integer
+      :tag_block,   # Integer — The finality-tag block; null on depth chains or when the node refuses the tag.
+      :tag_error,   # String
+      keyword_init: true
+    )
+
     # Operator diagnostics for GET /admin/health: one verdict plus a named check per standing failure
     # condition, always 200 (a degraded system is the content, not an error — this is not a liveness
     # probe). Every figure is computed on request from state the gateway already keeps; nothing here is
@@ -173,16 +216,6 @@ module Rail0
       keyword_init: true
     )
 
-    # A wallet's token holding, with the wallet, token, and blockchain nested via their own schemas.
-    WalletToken = Struct.new(
-      :default,     # Boolean
-      :active,      # Boolean
-      :wallet,      # Wallet
-      :token,       # Token
-      :blockchain,  # Blockchain
-      keyword_init: true
-    )
-
     # A wallet's token holding as nested under its wallet (GET /accounts/:id/wallets): the token plus
     # this wallet's per-token flags, without re-nesting the wallet.
     WalletTokenHolding = Struct.new(
@@ -239,14 +272,18 @@ module Rail0
 
     # Buyer-driven, signal-only dispute lifecycle (no fund effect).
     Dispute = Struct.new(
-      :id,            # String
-      :payment_id,    # String
-      :status,        # String
-      :reason,        # String — On-chain bytes32 reason code (hex).
+      :id,                        # String
+      :payment_id,                # String
+      :status,                    # String
+      :reason,                    # String — On-chain bytes32 reason the dispute was opened with (hex); the all-zero word when no reason was given; kept verbatim even when it is outside the dispute-reason dictionary.
+      :reason_code,               # DisputeOpenReason | nil — The DisputeOpenReason code `reason` reads as; null when no reason was given (the zero bytes32) or when the bytes32 is not in the dictionary (a direct contract call).
+      :reason_description,        # String — English description of `reason_code`; "No reason given" when `reason` is the zero bytes32; "Unrecognised reason" when it is a non-zero bytes32 outside the dictionary.
       :opened_block,
-      :opened_at,     # String
+      :opened_at,                 # String
       :closed_by,
-      :close_reason,
+      :close_reason,              # On-chain bytes32 close reason (hex); the all-zero word when closed with no reason; null while the dispute is open.
+      :close_reason_code,         # DisputeCloseReason | DisputeSystemCloseReason | nil — The code `close_reason` reads as: a DisputeCloseReason, or the system DisputeSystemCloseReason `full_refund` when a full refund auto-closed the dispute. Null while open, when closed with no reason (the zero bytes32), or when the bytes32 is not in the dictionary.
+      :close_reason_description,  # English description of `close_reason_code`; "No reason given" when `close_reason` is the zero bytes32; "Unrecognised reason" when it is a non-zero bytes32 outside the dictionary; null while open.
       :closed_block,
       :closed_at,
       keyword_init: true
@@ -297,15 +334,81 @@ module Rail0
     )
 
     # The account's own profile as the holder reads it (GET) and as a PATCH returns it — id, name,
-    # email, timestamps. Deliberately no admin/role field: the operator grant lives in a separate table,
-    # so a standard account's profile carries no trace of that axis. An ADMIN reading any account gets
-    # the whole record plus `admin` instead, which is a different shape and not this one.
+    # email, priority_tip, timestamps. Deliberately no admin/role field: the operator grant lives in a
+    # separate table, so a standard account's profile carries no trace of that axis. An ADMIN reading
+    # any account gets the whole record plus `admin` instead, which is a different shape and not this
+    # one.
     Account = Struct.new(
-      :id,          # String
-      :name,        # String
+      :id,            # String
+      :name,          # String
       :email,
+      :priority_tip,  # Boolean — Whether the merchant's own transactions tip the network's suggested priority fee (true, the default) or the chain's minimum tip (false: 0 on most chains, 25 gwei on Polygon PoS/Amoy). The buyer's dispute/close_dispute never read it.
+      :created_at,    # String
+      :updated_at,    # String
+      keyword_init: true
+    )
+
+    # An operator grant with the people named.
+    AdministratorFull = Struct.new(
+      :id,          # String
+      :account_id,  # String
+      :granted_by,  # String
+      :note,        # String
+      :expires_at,  # String
       :created_at,  # String
-      :updated_at,  # String
+      :account,     # Hash — The account's public shape (id, name, email, priority_tip, timestamps).
+      :grantor,     # Hash — The account's public shape (id, name, email, priority_tip, timestamps).
+      keyword_init: true
+    )
+
+    # One row of the operator audit log.
+    AdminAction = Struct.new(
+      :id,                 # String
+      :actor_account_id,   # String
+      :actor_address,      # String
+      :action,             # String
+      :resource_type,      # String
+      :resource_id,        # String
+      :target_account_id,  # String
+      :detail,             # Hash
+      :created_at,         # String
+      :actor,              # Hash — The account's public shape (id, name, email, priority_tip, timestamps).
+      :target_account,     # Hash — The account's public shape (id, name, email, priority_tip, timestamps).
+      keyword_init: true
+    )
+
+    # One reported policy value.
+    PolicySetting = Struct.new(
+      :value,       # The effective value (number, boolean, string, list or map).
+      :env,         # String — The environment variable that sets it; null for a constant.
+      :overridden,  # Boolean — Whether that variable is set in this process.
+      keyword_init: true
+    )
+
+    # GET /admin/policy: the effective policy, grouped. Every leaf is a PolicySetting.
+    PolicyReport = Struct.new(
+      :payments,      # Hash
+      :recovery,      # Hash
+      :retention,     # Hash
+      :webhooks,      # Hash
+      :settlement,    # Hash
+      :rate_limit,    # Hash
+      :siwe,          # Hash
+      :fees,          # Hash
+      :rpc,           # Hash
+      :generated_at,  # String
+      keyword_init: true
+    )
+
+    # GET /admin/catalog: the snapshot against the database, per table.
+    CatalogDiff = Struct.new(
+      :loaded_at,    # String
+      :checked_at,   # String
+      :stale,        # Boolean
+      :pending,      # Integer
+      :blockchains,  # Hash
+      :tokens,       # Hash
+      :contracts,    # Hash
       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.3.1"
+  VERSION = "1.5.0"
 end

data/lib/rail0/webhook_signature.rb

@@ -16,6 +16,12 @@ module Rail0
   #   X-Rail0-Timestamp  unix seconds, as a string
   #   X-Rail0-Signature  hex HMAC-SHA256 over "{timestamp}.{body}", keyed by the secret
   #
+  # and, for a grace window after a secret rotation (the gateway's
+  # WEBHOOK_SECRET_GRACE, one hour by default), X-Rail0-Signature-Previous: the same
+  # digest under the REPLACED secret, so an endpoint still holding the old key passes
+  # that header to {verify} instead and no delivery in flight at rotation is rejected.
+  # The old key signs only, and is never honoured past the window.
+  #
   # The timestamp is inside the signed string on purpose: without it a captured
   # delivery is replayable forever, because the body alone stays valid indefinitely.
   # That is why {verify} rejects a stale timestamp even when the digest matches —

data/lib/rail0.rb

@@ -18,3 +18,4 @@ require_relative "rail0/http_client"
 require_relative "rail0/client"
 require_relative "rail0/webhook_signature"
 require_relative "rail0/stablecoins"
+require_relative "rail0/dispute_reasons"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -41,6 +41,7 @@ files:
 - lib/rail0/backoff.rb
 - lib/rail0/client.rb
 - lib/rail0/default_logger.rb
+- lib/rail0/dispute_reasons.rb
 - lib/rail0/error_hints.rb
 - lib/rail0/http_client.rb
 - lib/rail0/request.rb