From 9820ee730cf766e07a4ee8939adbe09e60d42896 Mon Sep 17 00:00:00 2001 From: PIERLUIGI VITI Date: Mon, 17 Aug 2026 12:46:11 +0200 Subject: [PATCH] docs(types): chain_id on Payment, finality_tag on SyncBlockchain MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligns the typed reference with the current gateway surface. The structs in lib/rail0/types.rb are documentation — the resources return plain Hashes and never instantiate them — so this changes no behaviour, but a shape reference that omits a field is worse than none. - `Payment.chain_id` — the gateway moved it onto the payments LIST entity (commercelayer/rail0-gateway#193). It is what makes an amount renderable: `amount` is in base units and the token's decimals resolve from `token` PLUS its chain, an address alone being ambiguous across chains. - `SyncBlockchain.finality_tag` (commercelayer/rail0-gateway#195) — which block the chain calls settled; the indexer gates every notify on it. The `required_confirmations` comment now says it is the fallback for chains that serve no tag, which is what it became. README: the payments section states that every row carries `chain_id`, list rows included, so a listing needs no `get(id)` per row to display totals. Verified: `bundle exec rake` — 139 examples, 0 failures. Co-Authored-By: Claude Opus 5 --- README.md | 5 +++++ lib/rail0/types.rb | 6 +++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bc903e5..aa0d3d0 100644 --- a/README.md +++ b/README.md @@ -243,6 +243,11 @@ 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. + ### Refund (two-phase EIP-3009) ```ruby diff --git a/lib/rail0/types.rb b/lib/rail0/types.rb index 787e850..460edf3 100644 --- a/lib/rail0/types.rb +++ b/lib/rail0/types.rb @@ -164,6 +164,8 @@ module Types 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. :rail0_id, # String — Protocol-level identifier (66-char hex). :status, # String :mode, # String @@ -269,7 +271,9 @@ module Types SyncBlockchain = Struct.new( :chain_id, # Integer :start_block, # Integer - :required_confirmations, # 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. :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).