rail0-sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da765ab6a541e6af453972d5bf10ffc052daeac4c909bbb3ee6fb1e47ebee6fd
-  data.tar.gz: c17f6dce9b41d781e907141e77dbfbad5bc3392900c4003083cc3a0b3bb4ffb6
+  metadata.gz: 4f10297affa2fe993f9f4777ba2c6994610de8a6e2abe54d19b790cabfb09681
+  data.tar.gz: 75ea2a7fdcc4b18cd8b4d62c689bb9a2b0bcb2030793e24a12224ee205275490
 SHA512:
-  metadata.gz: dd490a0832f5814d3620d0d233e5d65bfa5790b9c2987e71b363fbcdf3462bb1b2d81bcb15321a2a7f72c2acf1064694c1b4ba036f35639613b54eb2ab68c787
-  data.tar.gz: e2aaf5625eb07f543d9b0429c2dbcff2333f723ebe2d44cf1b5bdb624f7df5876baff2cb437528914b18ef1270b20700df2a5cc5fb99348709875837a2587839
+  metadata.gz: 211b69279ade20a322f29061a5723ce477e42d6ff50f9f2b2b192569117ffcbc25f35ba32dbe2c56c88ac04501669856cc3f9613ad12a8a2433ba76cf15e4a62
+  data.tar.gz: 1e856d8c347d5793915bdbbceec990cc0bcc12f9e85977e293bc268fee9c4985d19cf114559199a9c88f58850b5e6f83e4e94d5d7e82f69f38036592d284be1e

data/README.md

@@ -15,7 +15,8 @@ lifecycle plus account, wallet, catalog, and webhook management. It mirrors the
 - Ruby ≥ 3.0
 - For SIWE login and off-chain signing: `eth` (`~> 0.5`) and `siwe-rb` (`~> 0.2`)
 
-The core HTTP client has **no runtime dependencies** (Ruby stdlib only). The `eth`
+The core HTTP client needs only the Ruby stdlib plus the `logger` gem (a declared
+dependency, since it is no longer a default gem from Ruby 4.0). The `eth`
 and `siwe-rb` gems are loaded lazily — `require "rail0"` works without them, and
 they are needed only when you call `client.auth.login` or `Rail0::Signing`.
 
@@ -167,7 +168,10 @@ path segments and does not fit the generic shape.
 
 ```ruby
 auth = client.auth.login(private_key: "0x…", domain: "api.rail0.xyz")
-# => { token:, address:, account_id:, name:, expires_at: }
+# => { token:, address:, account_id:, name:, expires_at:, admin: }
+# admin is always a boolean (verify too): true only for an account holding the
+# operator grant, false otherwise (visibility only). account_id/name are nil for an
+# account-less session.
 # login embeds chain_id 1 by default; pass chain_id: to match a gateway whose
 # SIWE_CHAIN_ID policy differs (e.g. login(private_key:, domain:, chain_id: 5042002)).
 
@@ -191,9 +195,9 @@ Lower-level building blocks are also available:
 
 ```ruby
 nonce   = client.auth.nonce                                  # POST /auth/nonces
-session = client.auth.verify(message: siwe_msg, signature: sig)  # POST /auth
+session = client.auth.verify(message: siwe_msg, signature: sig)  # POST /auth — same hash as login
 client.auth.logout                                           # POST /auth/logout
-client.auth.revoke_all                                       # POST /auth/revoke_all
+client.auth.revoke_all(private_key: "0x...", domain: "api.rail0.xyz")  # POST /auth/revoke_all
 ```
 
 `logout` revokes **the token this client carries**, not every session for the address —
@@ -207,14 +211,21 @@ live sessions would need five tokens you do not have. This is per **address** an
 the ones you never saw — including any an attacker is holding — which makes it the call
 for a key you no longer trust. The gateway records a cutoff **instant** rather than
 enumerating tokens, so a session minted a moment before the call is refused by its own
-`iat`; that is what makes it durable where a denylist is not. The returned `cutoff` is
-the field worth logging: it says exactly which sessions died, which `revoked: true`
-cannot.
+`iat`; that is what makes it durable where a denylist is not.
+
+It is authorized by a **fresh SIWE proof** of the address, not by the session — whoever
+is reacting to a leaked key holds the wallet, not the stolen token — so it takes the
+private key and domain (and optional `chain_id:`, default 1) exactly like `login`, and
+needs the same optional `eth`/`siwe-rb` gems. The proof carries its own statement
+(`"Sign out of RAIL0 everywhere"`), so a login signature cannot be replayed here. It is
+self-revoking: any token you hold dies too, so sign in again afterwards. It returns
+`{ revoked_all: true, cutoff_at: "<ISO-8601>" }`; `cutoff_at` is the field worth
+logging — it says exactly which sessions died, which `revoked_all: true` cannot.
 
 ## Catalog (public)
 
 ```ruby
-client.chains.list                                    # GET /blockchains
+client.chains.list                                    # GET /blockchains (each chain's :contract is the active RAIL0 deployment)
 client.chains.list(network_type: "testnet", symbol: "ETH")
 client.tokens.list                                    # GET /tokens
 client.tokens.list(chain_id: 84532, symbol: "USDC")
@@ -305,14 +316,15 @@ buyers, so it is the last step of merchant onboarding:
 
 ```ruby
 holding = client.wallets.add_token(account_id, id_or_address, chain_id: 84532, token: "0x…", default: true)
-client.wallets.enable_token(account_id, id_or_address, holding[:id])
-client.wallets.disable_token(account_id, id_or_address, holding[:id])  # keeps the holding
-client.wallets.remove_token(account_id, id_or_address, holding[:id])   # 204, soft delete
+client.wallets.enable_token(account_id, id_or_address, holding[:token_id])
+client.wallets.disable_token(account_id, id_or_address, holding[:token_id])  # keeps the holding
+client.wallets.remove_token(account_id, id_or_address, holding[:token_id])   # 204, soft delete
 ```
 
 `add_token` is idempotent by (wallet, chain, token): re-adding an existing holding
 re-enables it and answers 200 instead of creating a second row. The id passed to
-the other three is the **holding's** id, not the token address.
+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).
 
 ## Payments
 
@@ -365,8 +377,9 @@ client.payments.refund(rail0_id, { signed_transaction: raw })
 
 ### Disputes (payer-driven)
 
-Disputes are authorized on-chain by the payer (no JWT) and follow the same
-prepare → submit pattern:
+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:
 
 ```ruby
 prep = client.payments.dispute_prepare(rail0_id, reason: "0x…") # reason optional
@@ -709,6 +722,8 @@ lib/rail0/
   default_logger.rb    Rail0::LogEntry + Rail0::DefaultLogger (Logger subclass) for `logger:`
   api_error.rb         Rail0::ApiError (code/title/detail + #hint)
   error_hints.rb       Rail0.describe_error — per-code next steps, shared with the other SDKs
+  backoff.rb           Rail0::Backoff — retry delays and 429 jitter
+  webhook_signature.rb Rail0::WebhookSignature — delivery verification
   signing.rb           EIP-3009 + EIP-1559 signing (requires 'eth')
   stablecoins.rb       stablecoin address registry
   types.rb             generated Struct docs of the gateway schema (reference only)
@@ -721,6 +736,8 @@ lib/rail0/
     payment_methods.rb public payment-method discovery
     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)
     webhooks.rb        webhook subscription management (JWT)
     analytics.rb       account-scoped payment analytics (JWT)
     query.rb           shared query-string helper

data/lib/rail0/resources/auth.rb

@@ -31,6 +31,13 @@ module Rail0
       # account. Never collapse the two into a single constant.
       WALLET_LINK_STATEMENT = "Add this wallet to your RAIL0 account"
 
+      # The SIWE statement for revoking every session of an address —
+      # POST /auth/revoke_all. The gateway asserts it exactly
+      # (Policy::SIWE_REVOKE_ALL_STATEMENT) for the reason the other two are
+      # separate: a proof is spendable at exactly one endpoint, so a captured login
+      # signature cannot be replayed to sign its address out everywhere.
+      REVOKE_ALL_STATEMENT = "Sign out of RAIL0 everywhere"
+
       attr_reader :http
 
       def initialize(http)
@@ -47,9 +54,15 @@ module Rail0
       # Submit a pre-built SIWE message and its signature, returning a JWT.
       # @param message   [String] EIP-4361 formatted message string.
       # @param signature [String] 0x-prefixed hex signature.
-      # @return [Hash] { token:, address:, account_id:, name:, expires_at: }
+      # @return [Hash] { token:, address:, account_id:, name:, expires_at:, admin: }
+      #
+      # +admin+ is true only for an account holding the operator (administrators)
+      # grant: the gateway adds the field on an admin's session alone, and it is
+      # normalised here to a boolean so a standard login reads false rather than nil.
+      # Visibility only — every gated route re-checks the grant per request.
       def verify(message:, signature:)
-        http.post("/auth", { message: message, signature: signature })
+        session = http.post("/auth", { message: message, signature: signature })
+        session.merge(admin: session[:admin] == true)
       end
 
       # End the session whose token this client carries.
@@ -70,23 +83,43 @@ module Rail0
         http.post("/auth/logout", {})
       end
 
-      # End EVERY session of the calling address (POST /auth/revoke_all).
+      # End EVERY session of the address controlled by +private_key+
+      # (POST /auth/revoke_all).
       #
       # The answer to a key you no longer trust, and {#logout} cannot be that answer: it
       # is per TOKEN, so an address with five live sessions needs five tokens the caller
       # does not have. This is per ADDRESS and reaches the ones it never saw — including
       # any an attacker is holding.
       #
+      # Authorized by a FRESH SIWE PROOF of the address, not by the session: someone
+      # reacting to a leaked key holds the wallet, not the stolen token, so requiring the
+      # session would make this useless exactly when it is needed. The proof is the same
+      # handshake as {#login} — fetch a single-use nonce, build an EIP-4361 message, sign
+      # it with EIP-191 personal_sign — but carries {REVOKE_ALL_STATEMENT}, so a login
+      # proof cannot be replayed here (the gateway answers 422 siwe_purpose_mismatch).
+      # This method used to post an empty body, which the gateway refused on every call,
+      # and read `revoked`/`cutoff`, which the gateway never sends.
+      #
       # The gateway records a cutoff INSTANT rather than enumerating tokens, so a session
-      # minted a moment before the call is refused by its own `iat`. That is what makes it
-      # durable where a denylist is not: there is nothing to enumerate and nothing to miss.
+      # minted a moment before the call is refused by its own `iat`. It is self-revoking:
+      # the cutoff is just after now, so any token this caller holds dies with the rest —
+      # sign in again afterwards. (The client does not store the JWT, so there is nothing
+      # local to clear; drop your own copy.)
       #
-      # `cutoff` is the field worth logging. It says exactly which sessions died, which
-      # `revoked: true` cannot.
+      # `cutoff_at` is the field worth logging. It says exactly which sessions died, which
+      # `revoked_all: true` cannot.
       #
-      # @return [Hash] { revoked: true|false, cutoff: "2026-08-27T21:00:00Z" }
-      def revoke_all
-        http.post("/auth/revoke_all", {})
+      # Requires the optional 'eth' and 'siwe-rb' gems.
+      #
+      # @param private_key [String] 0x-prefixed hex private key of the address to sign out.
+      # @param domain      [String] Host of the API server (e.g. "api.rail0.xyz").
+      # @param chain_id    [Integer] Chain ID to embed; same meaning and default as #login.
+      # @return [Hash] { revoked_all: true, cutoff_at: "2026-09-24T18:00:01Z" } — cutoff_at
+      #   is an ISO-8601 instant; every token of the address issued before it is refused.
+      def revoke_all(private_key:, domain:, chain_id: 1)
+        message, signature = sign_proof(private_key, domain, chain_id, REVOKE_ALL_STATEMENT)
+        result = http.post("/auth/revoke_all", { message: message, signature: signature })
+        { revoked_all: result[:revoked_all], cutoff_at: result[:cutoff_at] }
       end
 
       # Perform the full SIWE authentication flow:
@@ -102,7 +135,7 @@ module Rail0
       # @param chain_id    [Integer] Chain ID to embed in the SIWE message. Must match
       #   the gateway's SIWE_CHAIN_ID policy (default 1); override only when the
       #   gateway is configured with a different login chain.
-      # @return [Hash] { token:, address:, account_id:, name:, expires_at: }
+      # @return [Hash] { token:, address:, account_id:, name:, expires_at:, admin: }
       def login(private_key:, domain:, chain_id: 1)
         message, signature = sign_proof(private_key, domain, chain_id, LOGIN_STATEMENT)
         verify(message: message, signature: signature)
@@ -135,9 +168,9 @@ module Rail0
 
       private
 
-      # The shared core of both handshakes. Everything but the STATEMENT is
-      # identical, which is precisely why the statement is a parameter and never a
-      # default — see the note on the two constants.
+      # The shared core of every SIWE handshake (login, prove_address, revoke_all).
+      # Everything but the STATEMENT is identical, which is precisely why the
+      # statement is a parameter and never a default — see the note on the constants.
       def sign_proof(private_key, domain, chain_id, statement)
         ensure_signing_deps!
 

data/lib/rail0/resources/wallets.rb

@@ -135,8 +135,10 @@ module Rail0
 
       # Stop accepting a token on this wallet (soft delete). Returns HTTP 204.
       #
-      # `token_id` is the id of the HOLDING as returned by {add_token} / {list}'s
-      # nested `tokens`, not the token's contract address.
+      # `token_id` is the TOKEN's UUID — the `token_id` field on a holding returned
+      # by {add_token} / {list}'s nested `tokens` — not an id of the holding row and
+      # 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}.
       #
       # @return [nil]
       def remove_token(account_id, id_or_address, token_id)

data/lib/rail0/stablecoins.rb

@@ -78,13 +78,50 @@ module Rail0
           "cUSD" => StablecoinInfo.new(address: "0x765DE816845861e75A25fCA122bb6898B8B1282a", decimals: 18, eip3009: true, eip2612: false),
           "cEUR" => StablecoinInfo.new(address: "0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73", decimals: 18, eip3009: true, eip2612: false)
         }
+      ),
+      # ── Testnets ───────────────────────────────────────────────────────────
+      # Every address below was read off its own chain, and the token lists are
+      # the immutable acceptedTokens() allowlists of the RAIL0 deployments there
+      # — which is what a payment on that chain can actually use.
+      "arc-testnet" => ChainStablecoins.new(
+        chain_id: 5042002,
+        tokens: {
+          "USDC" => StablecoinInfo.new(address: "0x3600000000000000000000000000000000000000", decimals: 6, eip3009: true, eip2612: true),
+          "EURC" => StablecoinInfo.new(address: "0x89B50855Aa3bE2F677cD6303Cec089B5F319D72a", decimals: 6, eip3009: true, eip2612: true)
+        }
+      ),
+      # Celo Sepolia is 11142220. The rail0-go registry carried 44787 here, which is
+      # ALFAJORES — a different, now-retired network — alongside a USDC address with
+      # no code on this chain. Corrected there in the same change; do not "restore" it.
+      "celo-sepolia" => ChainStablecoins.new(
+        chain_id: 11142220,
+        tokens: {
+          "USDC" => StablecoinInfo.new(address: "0x01C5C0122039549AD1493B8220cABEdD739BC44E", decimals: 6, eip3009: true, eip2612: true),
+          "USD₮" => StablecoinInfo.new(address: "0xd077A400968890Eacc75cdc901F0356c943e4fDb", decimals: 6, eip3009: true, eip2612: true)
+        }
+      ),
+      # PYUSD is the first non-Circle token served, and the reason this chain is
+      # served at all — it is issued nowhere else.
+      #
+      # Signing against PYUSD directly: its EIP-712 domain name is "PayPal USD", not
+      # the symbol, and its version is "1", which version() does not expose (it
+      # reverts). Through a RAIL0 payment this never bites — the domain comes down in
+      # the gateway's signing_payload — but building the domain by hand from the
+      # symbol yields a signature the token rejects.
+      "ethereum-sepolia" => ChainStablecoins.new(
+        chain_id: 11155111,
+        tokens: {
+          "USDC"  => StablecoinInfo.new(address: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238", decimals: 6, eip3009: true, eip2612: true),
+          "PYUSD" => StablecoinInfo.new(address: "0xCaC524BcA292aaade2DF8A05cC58F0a65B1B3bB9", decimals: 6, eip3009: true, eip2612: true)
+        }
       )
     }.freeze
 
     # Returns the registry entry for a chain, or +nil+ if the chain is unknown.
     #
     # Supported chain names: "ethereum", "base", "polygon", "arbitrumOne",
-    # "optimism", "avalanche", "celo".
+    # "optimism", "avalanche", "celo", "arc-testnet", "celo-sepolia",
+    # "ethereum-sepolia".
     #
     # @param chain [String]
     # @return [ChainStablecoins, nil]

data/lib/rail0/types.rb

@@ -46,36 +46,43 @@ module Rail0
       keyword_init: true
     )
 
-    # Error envelope. Every error this API returns carries `code` (stable and machine-readable — the
-    # only field to branch on), `title` (a short label) and `detail` (one or two sentences fit to show a
-    # user verbatim). The wording comes from the gateway's error catalogue, so the same condition always
-    # reads the same way wherever it surfaces. `status` and `message` are the pre-code/title/detail
-    # names, derived from the same entry and kept for existing clients: `status` carries the family a
-    # client used to switch on (e.g. `forbidden`, `invalid_state`) where `code` is narrower, and
-    # `message` equals `detail`. Context fields may also be present (`resource`, `param`, `chain_id`,
-    # `token`, `payee`, `errors`).
+    # The error envelope: exactly code (stable, the only field to branch on), title (short label) and
+    # detail (a sentence a UI can print verbatim). The legacy status/message/error aliases were removed
+    # in #252.
     ApiErrorBody = Struct.new(
-      :code,     # String
-      :title,    # String
-      :detail,   # String
-      :status,   # String — Legacy: the error family, or the code itself when there is no wider family.
-      :message,  # String — Legacy alias of `detail`.
+      :code,    # String
+      :title,   # String
+      :detail,  # String
       keyword_init: true
     )
 
-    # Gateway liveness/readiness. Only the database gates the HTTP code (200 healthy, 503 when the DB is
-    # unreachable); Sidekiq is reported but never flips the code, since the API still serves synchronous
-    # requests when workers are down. `status` is the global signal: `ok` (all good), `degraded` (DB ok
-    # but Sidekiq not ok), `error` (DB down — the only 503).
+    # Gateway liveness/readiness — public and token-blind: one body for every caller, and every field is
+    # public by nature (the versions are on-chain / on the root descriptor; the counts are derivable
+    # from the public catalog reads). Only the database gates the HTTP code (200 healthy, 503 when the
+    # DB is unreachable); the Sidekiq worker fleet never flips the code, since the API still serves
+    # synchronous requests when workers are down. `status` is the global signal: `ok` (all good),
+    # `degraded` (DB ok but the worker fleet not ok), `error` (DB down — the only 503). The fleet
+    # FIGURES (queue depth, worker count, Redis reachability) are operational internals and live on the
+    # operator-only GET /admin/health.
     Health = Struct.new(
       :status,            # String
+      :db,                # String
+      :timestamp,         # String
       :api_version,       # String
       :contract_version,  # String
-      :db,                # String
-      :sidekiq,           # Hash — Worker fleet health (does not gate liveness).
       :active_chains,     # Integer
       :active_contracts,  # Integer
-      :timestamp,         # 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
+    # a counter anyone increments.
+    AdminHealth = Struct.new(
+      :status,     # String — The worst of the checks. Exists so "is anything wrong" can be read without knowing which checks there are, nor which will be added later.
+      :checks,     # Hash
+      :timestamp,  # String
       keyword_init: true
     )
 
@@ -89,7 +96,9 @@ module Rail0
     # Issued after a successful SIWE verification. SIWE alone proves control of the address, so a token
     # is issued even when the address is not registered to any account; in that case `account_id` and
     # `name` are null (an account-less session, e.g. a buyer). Clients that require an account must
-    # treat a null `account_id` as not-allowed.
+    # treat a null `account_id` as not-allowed. A session whose account holds the operator grant
+    # additionally carries `admin: true` (the Session::Admin variant); a standard or account-less
+    # session has no admin/role field at all.
     Session = Struct.new(
       :token,       # String — JWT bearer token.
       :address,     # String — Resolved wallet address.
@@ -99,20 +108,31 @@ module Rail0
       keyword_init: true
     )
 
+    # The RAIL0 deployment a NEW payment on this chain is opened against — what escrows the payer's
+    # funds, and which version of it. Nothing here is a disclosure: the address is on-chain, every
+    # payment response already carries it as `rail0_contract`, and the explorer shows its verified
+    # source. It is published so a client does not carry its own address-per-chain table and go quietly
+    # stale on the next rollout. Null only for a chain with no deployment, which cannot appear in this
+    # listing anyway. The operator's bookkeeping (start_block, active/archived) stays on
+    # /admin/contracts: it describes how this gateway and its indexer are run, not what a payer is
+    # signing into.
+    ChainContract = Struct.new(
+      :address,      # String
+      :version,      # String — Semver of the deployed contract. Every active deployment agrees on the one the gateway targets.
+      :deployed_at,  # String
+      keyword_init: true
+    )
+
     # Public blockchain view.
-    #
-    # required_confirmations and finality_tag together say how long a payer waits. Read
-    # the PAIR, not the number: where a chain serves a finality tag the gateway gates on
-    # that tag, and the count is the fallback for chains serving none — so quoting the
-    # count on a tagged chain names a wait nobody applies.
     Blockchain = Struct.new(
-      :chain_id,               # Integer
-      :name,                   # String
-      :native_symbol,          # String
-      :network_type,           # String
-      :explorer_url,           # String
-      :required_confirmations, # Integer
-      :finality_tag,           # String, nil where the chain serves no tag
+      :chain_id,                # Integer
+      :name,                    # String
+      :native_symbol,           # String
+      :network_type,            # String
+      :explorer_url,            # String
+      :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
       keyword_init: true
     )
 
@@ -150,9 +170,10 @@ module Rail0
     # 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(
-      :token,    # Token
-      :active,   # Boolean
-      :default,  # Boolean
+      :token_id,  # String — The token's UUID — the handle for PATCH/DELETE /accounts/{account_id}/wallets/{id}/tokens/{token_id}.
+      :token,     # Token
+      :active,    # Boolean
+      :default,   # Boolean
       keyword_init: true
     )
 
@@ -167,28 +188,25 @@ module Rail0
       keyword_init: true
     )
 
-    # Base persisted payment fields.
+    # Base persisted payment fields, plus the `chain_id` of the payment's deployment.
     Payment = Struct.new(
       :id,                    # String
       :contract_id,           # String
-      :chain_id,              # Integer — EVM chain id of the deployment. On list rows too: `amount` is
-      #                         base units, and the token's decimals resolve from `token` PLUS its chain.
+      :chain_id,              # Integer — EVM chain id of the payment's deployment. Present on the list view too: `amount` is in base units, and the token's `decimals` can only be resolved from `token` together with its chain.
       :rail0_id,              # String — Protocol-level identifier (66-char hex).
-      :status,                # String
+      :status,                # String — Lifecycle state. Deliberately a HAPPY-PATH label, not a ledger: a partial operation does NOT move it, so a payment captured 100 and refunded 40 still reads `captured`, and a full refund that leaves uncaptured escrow does too. `capturable_amount` / `refundable_amount` are the authoritative residuals — reconcile on those, not on this. `partially_refunded` is retained for historical rows only and is no longer produced.
       :mode,                  # String
       :amount,                # String
       :capturable_amount,     # String — Mirrors on-chain capturableAmount (escrow still held); base units.
       :refundable_amount,     # String — Mirrors on-chain refundableAmount (held by payee, still refundable); base units.
-      # The window after a PARTIAL capture where neither void nor release can return the
-      # buyer's remaining escrow — the answer to "why did both just refuse?".
-      :escrow_stranded,       # Boolean
-      :escrow_returnable_at,  # String, nil — ISO-8601 end of that window; nil outside it.
       :config_hash,           # String
       :payer,                 # String
       :payee,                 # String
       :token,                 # String
       :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.
       :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.
@@ -218,15 +236,16 @@ module Rail0
     Transaction = Struct.new(
       :id,                    # String
       :payment_id,            # String
-      :operation,             # String
+      :operation,             # String — Which on-chain call this row attempts. A SUPERSET of the `{operation}` path enum: `dispute` and `close_dispute` have their own hand-written routes rather than living under the generic namespace, but they mint transaction rows like any other operation, so a generated client must be able to represent them.
       :status,                # String
+      :redrivable,            # Boolean — True when this transaction's broadcast can be re-enqueued: it is `pending` and the gateway holds its signed transaction, i.e. a send that was prepared and signed but never reached the chain. The same predicate `POST /payments/{id}/transactions/{transaction_id}/redrive` guards on, so a client can offer the action exactly when it will succeed instead of on a 422. False on a `pending` row that holds no signed transaction - there the next step is submitting the signature, not a redrive.
       :error_code,            # Decoded failure code, null unless `status` is "failed". Same catalogue as an error body's `code`: a RAIL0 custom error (`not_payee`), a token-level revert (`insufficient_token_balance`, `invalid_token_signature`, `authorization_already_used`), a Solidity panic, or a rejection that stopped the broadcast before the chain saw it (`insufficient_gas_funds`, `nonce_too_low`).
       :error_title,           # String — Short label for `error_code`; null unless failed.
       :error_detail,          # String — Sentence explaining the failure; null unless failed. Carries the chain's own words when the revert was not one the gateway recognises.
-      :error_message,         # Legacy alias of `error_detail`.
       :unsigned_transaction,
       :transaction_hash,
-      :amount,
+      :sender,                # The address that SIGNED the submitted transaction, recovered from the signature by the gateway at submit — a fact, not a client claim. Null where the gateway held no signature to recover from (a report-by-hash submit, where the wallet broadcast it itself) or where nothing has been submitted yet. This is what makes `release` gas attributable: that operation is payer-OR-payee, so whose cost it is depends on who signed.
+      :amount,                # Amount in token BASE units. On capture and refund it is the amount the caller asked for. On void and release it is PROVISIONAL — those operations carry no amount and move the whole uncaptured escrow, so this is the capturable residual as of prepare, re-sealed with the exact on-chain amount when the indexer confirms.
       :block_number,
       :gas_used,              # Gas units used, mirrored from the indexer on confirm.
       :gas_limit,             # Gas limit, mirrored from the indexer on confirm.
@@ -241,11 +260,41 @@ module Rail0
       keyword_init: true
     )
 
+    # Full RAIL0 deployment row (admin surfaces only). Read alongside AdminBlockchain: a chain with no
+    # row here cannot take a payment, which is what keeps it out of service.
+    AdminContract = Struct.new(
+      :id,             # String
+      :blockchain_id,  # String
+      :address,        # String
+      :version,        # String — Semver, and every ACTIVE deployment must agree on the one the code targets.
+      :deployed_at,    # String
+      :start_block,    # Where the indexer starts. Null means the deployment block.
+      :active,         # Boolean — The single deployment new payments are opened against, at most one per chain.
+      :archived,       # Boolean — Always false here: the listing excludes archived deployments.
+      :archived_at,
+      :created_at,     # String
+      :updated_at,     # String
+      keyword_init: true
+    )
+
+    # 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.
+    Account = Struct.new(
+      :id,          # String
+      :name,        # String
+      :email,
+      :created_at,  # String
+      :updated_at,  # String
+      keyword_init: true
+    )
+
     Webhook = Struct.new(
       :id,                     # String
       :name,                   # String
       :callback_url,           # String
-      :topics,                 # Array<WebhookTopic> — every event this subscription delivers
+      :topics,                 # Array — Every event this subscription delivers. The delivery itself names the one that fired, in X-Rail0-Topic.
       :active,                 # Boolean
       :circuit_state,          # String
       :circuit_failure_count,  # Integer
@@ -272,7 +321,7 @@ module Rail0
     # Sweeper view of a stale submitted transaction.
     SyncTransaction = Struct.new(
       :transaction_hash,  # String
-      :operation,         # String
+      :operation,         # String — Same vocabulary as `Transaction.operation` — dispute rows go stale too.
       :payment_id,        # String — Protocol-level rail0_id.
       :chain_id,          # Integer
       keyword_init: true
@@ -283,8 +332,7 @@ module Rail0
       :chain_id,                # Integer
       :start_block,             # Integer
       :required_confirmations,  # Integer — Fallback burial depth, used where the chain serves no finality tag.
-      :finality_tag,            # String — Which block the chain calls settled ("safe", "finalized" or
-      #                           "depth"); the indexer gates every notify on it.
+      :finality_tag,            # String — Which block the chain calls settled; the indexer gates every notify on it.
       :explorer_url,            # Block explorer base URL; null when the chain has none.
       :network_type,            # String — "testnet" or "mainnet"; selects which chains a deployment indexes.
       :rpc_urls,                # Array — Ordered list of public RPC endpoints tried in turn (serial fallback).

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.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-21 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger