rail0-sdk 1.9.0 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e9c4a0434db81266c43b414c1f3f2f4b6f2466ef7aa9f1f4f1e1406542fabdf
-  data.tar.gz: a01332eba373c295821bd20edaa16076f4ef20b9fdb204064a0c9c378a5b8f1b
+  metadata.gz: ef5875508f67b6ca5ba08aa397f5afa33ad2fb1d3c53d956c1ea5c1f6f0c066c
+  data.tar.gz: 251404c40cce8af924a7b0ffded8052adb3a0fdea8c0f91345a3a9f7dceae3ba
 SHA512:
-  metadata.gz: abc0ca11b0940752160e3503087fd89d62c1e8ba04b5c6412cdef41751b598b25acd988fb52e4b04aa5a2c2e64c6fafdf0a72625eceb98238e0e2abd6a955e55
-  data.tar.gz: 9267bc67421f3aa0867c5c9b24a959679d1c648ea5e9598df149743a06efa76db088ea9f1b21a39a46c0f2974376ceadf783e34a65b59f1d846a5ae603c08464
+  metadata.gz: d3bcef6de15169f95b428d03e16336373f1e234b3c4a7e3aa987ddd72a9e34cdeddb7bb0359e0b03534c60209e89dc50e7a0014d45ff2b4e0c676b2e34df98d4
+  data.tar.gz: 8d2d98affb4443432e676d9008aa0a73486946884fc5905e2a44b99fdbad75eec123217b10d4818de8df29d2aad98e410c621552ce435697a5bb0988fcb70bd9

data/README.md

@@ -652,13 +652,17 @@ client.payments.submit_by_hash(id, "capture", { transaction_hash: "0x…" })
 A payout moves the merchant wallet's balance to a **payout destination** — a deposit
 address at an exchange, Circle Mint, an off-ramp provider or your own custody. It is a
 plain ERC-20 `transfer(address,uint256)` from the wallet, signed by the destination's own
-wallet; rail0 never holds the key. Destination amounts (`reserve_amount`, `min_amount`)
-are **base-unit** strings; the `*_formatted` fields beside them carry the human decimals.
+wallet; rail0 never holds the key. Destination amounts (`min_amount`) are **base-unit**
+strings; the `*_formatted` fields beside them carry the human decimals.
 
 ### 1. Register a destination (with the confirmation)
 
 Generate the deposit address at the venue **with the network set to the payout's chain**,
-note the venue's minimum deposit, then register it. `confirm_details:` is required and has
+note the venue's minimum deposit, then register it. The minimum is required, as exactly one
+of `min_amount:` (the venue's figure in base units, from its deposit page) or
+`no_minimum: true` (the merchant states the venue has none). Neither, a blank figure, or both
+raise `ArgumentError` before anything is sent, and nothing is defaulted: a minimum nobody
+looked up is how a deposit gets lost. `confirm_details:` is required and has
 no default: `true` is the merchant's acceptance of the gateway's `details_v1` text
 (`Rail0::Resources::PayoutDestinations::CONFIRM_DETAILS_TEXT`), recorded with who and when:
 
@@ -669,17 +673,24 @@ no default: `true` is the merchant's acceptance of the gateway's `details_v1` te
 Show that text and pass the merchant's answer; anything but `true` is 422
 `confirmation_required` and nothing is saved.
 
+`label:` is required too: the name the merchant knows the destination by. The gateway trims
+it, and it must be unique among the account's live destinations, compared without regard to
+case (409 `payout_destination_label_taken`; deleting a destination frees its label). A blank
+or whitespace-only label raises `ArgumentError` before anything is sent (the gateway's 422
+`label_required`).
+
 ```ruby
 dest = client.payout_destinations.create(
   wallet_id: WALLET_ID,               # the session's own wallet (uuid or address)
   chain_id: 5042002, token: USDC, address: VENUE_DEPOSIT_ADDRESS,
-  label: "Kraken", kind: "exchange",  # exchange | circle_mint | self_custody | provider
-  min_amount: "5000000",              # the venue's minimum, base units (5 USDC); omit for none
+  label: "Kraken",                    # required, unique per account (case-insensitive)
+  min_amount: "5000000",              # the venue's minimum, base units (5 USDC) — or no_minimum: true
   confirm_details: merchant_accepted  # true only once the merchant accepted the text above
 )
 dest[:status]                         # => "unverified"
 
 client.payout_destinations.list(status: "verified")       # paged like payments
+client.payout_destinations.list(include_deleted: true)     # deleted ones too (deleted_at set)
 client.payout_destinations.get(dest[:id])
 client.payout_destinations.events(dest[:id])               # audit trail, newest first
 ```
@@ -699,7 +710,7 @@ client.payout_destinations.confirm(dest[:id])              # => status "verified
 
 ### 3. Pay out: prepare → verify → sign → submit
 
-`amount` is a **human decimal** or `"all"` (the balance minus the reserve, below). A payout
+`amount` is a **human decimal** or `"all"` (the balance minus what is kept back, below). A payout
 below the destination's `min_amount` is refused 422 `payout_below_minimum`.
 
 ```ruby
@@ -744,25 +755,65 @@ cancelled (409 `payout_already_signed`): `resend` it and let it settle.
 A runnable end-to-end flow (register → proof → confirm → payout → poll) is in
 [`examples/06_payouts.rb`](examples/06_payouts.rb).
 
-### Minimum and reserve
+### Minimum, reserves, disable and delete
 
 - **Minimum** (`min_amount`): the venue's minimum deposit. Below it the venue may never
-  credit a transfer, so the gateway refuses it. Changing it needs the same confirmation, and
-  raising it above the latest proof takes the verification away (prove it again):
+  credit a transfer, so the gateway refuses it. It is required and explicit: a figure
+  (`"0"` included), or `no_minimum: true` when the venue has none — the destination then
+  reads `no_minimum: true` with `min_amount` nil (`no_minimum: false` with a nil `min_amount`
+  is a destination registered before the minimum was asked: never stated). A blank figure,
+  or a figure beside `no_minimum: true`, raises `ArgumentError` (the gateway's
+  `minimum_required` / `minimum_conflict`). Changing either needs the same confirmation, and
+  raising the minimum above the latest proof takes the verification away (prove it again):
 
   ```ruby
   client.payout_destinations.update(dest[:id], min_amount: "10000000", confirm_details: merchant_accepted)
-  client.payout_destinations.update(dest[:id], min_amount: "", confirm_details: merchant_accepted)  # none
+  client.payout_destinations.update(dest[:id], no_minimum: true, confirm_details: merchant_accepted) # none
+  ```
+
+- **Reserves**: what a payout keeps back in the wallet is decided at payout time, not stored
+  on the destination. The **refund reserve** is the refundable balance of the wallet's
+  payments in this token still inside their refund window (a refund is pulled from the payee
+  wallet, so an emptied wallet fails it). The **gas reserve**, only on a chain whose gas is
+  paid in this very token (Arc's USDC, `native_gas`), is the gas for those refunds and for
+  capturing the open authorizations plus a base of new captures; `"0"` elsewhere. On such a
+  chain the payout's own fee (`gas_allowance`) is always kept back too. `reserves` shows the
+  figures right now, with `available`: what `"all"` moves with both reserves kept:
+
+  ```ruby
+  r = client.payout_destinations.reserves(dest[:id])
+  r[:refund_reserve_formatted]  # => "40.00"   (r[:refundable_payments] payments)
+  r[:gas_reserve_formatted]     # => "0.12"
+  r[:available_formatted]       # => "960.00"  what amount: "all" moves
+  ```
+
+  Both reserves are kept by default. A payout can opt out of either (a refund or capture after
+  it may then fail for lack of funds); the payout records what it kept back in
+  `refund_reserve` / `gas_reserve` (base units, nil for a proof):
+
+  ```ruby
+  client.payouts.prepare(destination_id: dest[:id], amount: "all", keep_refund_reserve: false)
+  client.payouts.prepare(destination_id: dest[:id], amount: "all", keep_gas_reserve: false)
+  ```
+
+- **Rename**: `label:` renames it, under the same rules as on create: never blank
+  (`ArgumentError` here, 422 `label_required` at the gateway) and unique per account,
+  case-insensitive (409 `payout_destination_label_taken`):
+
+  ```ruby
+  client.payout_destinations.update(dest[:id], label: "Kraken main")
   ```
 
-- **Reserve** (`reserve_amount`): what an `"all"` payout leaves in the wallet so refunds can
-  still be paid. Unset, the gateway's suggestion applies (`suggested_reserve`: the refundable
-  balance of payments still inside their refund window).
+- **Disable and delete**: `active: false` disables a destination (`true` re-enables it with
+  the verification it had). `delete` removes it from the lists and frees its payment method
+  (one destination per token and chain, so another address can be registered there) and its
+  label; the row is kept (`get` and `events` still read it, with `deleted_at` set
+  and `status` `"disabled"`). Either settles a pending payout first: an unsigned one is
+  cancelled, a signed one refuses with 409 `payout_already_signed`.
 
   ```ruby
-  client.payout_destinations.update(dest[:id], reserve_amount: "100000000")
-  client.payout_destinations.update(dest[:id], reserve_amount: "")   # back to the suggestion
-  client.payout_destinations.update(dest[:id], active: false)        # disable (true re-enables)
+  client.payout_destinations.update(dest[:id], active: false)  # disable (true re-enables)
+  client.payout_destinations.delete(dest[:id])                 # soft delete, own wallet only
   ```
 
 ## Webhooks (JWT)
@@ -1220,7 +1271,7 @@ lib/rail0/
     accounts.rb        the caller's own account profile, read and update (JWT)
     webhooks.rb        webhook subscription management (JWT)
     analytics.rb       account-scoped payment analytics (JWT)
-    payout_destinations.rb payout destinations: register, confirm, update (JWT)
+    payout_destinations.rb payout destinations: register, confirm, update, delete, reserves (JWT)
     payouts.rb         merchant payouts: prepare, sign, submit (JWT)
     query.rb           shared query-string and path-segment helpers
 ```

data/lib/rail0/error_hints.rb

@@ -114,23 +114,27 @@ module Rail0
     "onboarding_link_expired" => "the link has expired — sign up again, or ask your RAIL0 contact for a new link",
     "onboarding_link_superseded" => "a newer link was sent for this request and this one no longer works — use the link in the most recent email",
     # Payouts (gateway#455): the merchant's transfer of its balance to a payout destination.
-    "confirmation_required" => "registering a payout destination, or changing its min_amount, needs confirm_details: true — the merchant's confirmation that they checked the address, network, token and minimum deposit at the venue (PayoutDestinations::CONFIRM_DETAILS_TEXT)",
-    "payout_destination_exists" => "this wallet already has a destination with this address for this token and chain — use it (payout_destinations.list)",
+    "confirmation_required" => "registering a payout destination, or changing its min_amount or no_minimum, needs confirm_details: true — the merchant's confirmation that they checked the address, network, token and minimum deposit at the venue (PayoutDestinations::CONFIRM_DETAILS_TEXT)",
+    "payout_destination_exists" => "this payment method (token and chain) already has a destination — one per method; delete it to register another address (payout_destinations.list)",
+    "payout_destination_label_taken" => "another destination of this account already has this label (compared without regard to case) — pick another name, or delete that destination to free it (payout_destinations.list)",
+    "label_required" => "a payout destination needs a label — a name, not blank or whitespace (payout_destinations.create / update)",
     "payout_destination_zero_address" => "the zero address cannot receive a payout — register the venue's deposit address",
     "payout_destination_own_wallet" => "the destination is the paying wallet itself — register the deposit address of the exchange, Circle Mint account or another wallet you control",
     "payout_destination_is_contract" => "the address is a RAIL0 contract or a token contract on this chain, where funds cannot be recovered — register the venue's deposit address",
     "payout_destination_disabled" => "the destination is disabled — re-enable it (payout_destinations.update(id, active: true)) or choose another one",
     "payout_destination_unverified" => "the destination is not verified: send the proof (payouts.prepare(purpose: \"proof\")), wait for it to confirm, check the venue credited it, then payout_destinations.confirm — until then only the proof amount can be sent",
     "payout_destination_proof_missing" => "the proof transfer has not confirmed on-chain yet — prepare, sign and submit it (purpose: \"proof\"), wait for payouts.get to say confirmed, then confirm the destination",
-    "payout_below_minimum" => "the amount is below the destination's min_amount (the venue may never credit it) — send at least the minimum; for \"all\", the balance after the reserve is below it",
-    "insufficient_balance" => "the wallet does not hold enough of the token for this amount after the refund reserve — the detail names what is available",
+    "minimum_required" => "a payout destination needs its venue's minimum deposit: min_amount (base units, from the venue's deposit page), or no_minimum: true when the venue has none — a blank min_amount is not one (to remove a minimum, send no_minimum: true)",
+    "minimum_conflict" => "min_amount and no_minimum: true contradict each other — send the venue's minimum, or no_minimum: true when it has none, not both",
+    "payout_below_minimum" => "the amount is below the destination's min_amount (the venue may never credit it) — send at least the minimum; for \"all\", the balance after what is kept back (reserves, gas) is below it",
+    "insufficient_balance" => "the wallet does not hold enough of the token for this amount after what the payout keeps back (refund reserve, gas reserve, gas allowance) — the detail names what is available; payout_destinations.reserves(id) shows the figures",
     "payout_limit_reached" => "this wallet reached its hourly payout limit — retry later",
     "payout_already_signed" => "the payout already holds a signed transaction that may still be mined — resend it (payouts.resend) and let it settle; it cannot be re-prepared or cancelled",
     "payout_not_pending" => "the payout is already submitted or settled — prepare a new one",
     "payout_not_signed" => "the payout holds no signed transaction to resend — submit the signed transfer first",
     "payout_hash_in_use" => "another payout already records this transaction hash — one transaction settles one payout",
     "foreign_transfer_hash" => "the reported transaction does not move this payout's amount of its token to its destination — report the hash of the transfer you broadcast for this payout",
-    "invalid_amount" => "the amount is not valid: base units (digits only, below 2^120) for reserve_amount/min_amount, a positive decimal within the token's decimals elsewhere",
+    "invalid_amount" => "the amount is not valid: base units (digits only, below 2^120) for min_amount, a positive decimal within the token's decimals elsewhere",
     "invalid_transaction" => "the signed transaction could not be decoded, or its sender is not allowed here — sign the prepare's unsigned_transaction unmodified with the right wallet",
     "unknown_chain" => "that chain id is not configured on this gateway — see chains.list",
     # A BARE forbidden is not a party mismatch: the gateway split those into codes of

data/lib/rail0/resources/payout_destinations.rb

@@ -13,8 +13,10 @@ module Rail0
     # merchant has checked the venue credited it ({#confirm}). Until then it can receive the
     # proof amount at most. See {Payouts} for the transfer itself.
     #
-    # Amounts on a destination (+reserve_amount+, +min_amount+) are BASE-UNIT strings (digits
-    # only, below 2^120); the +*_formatted+ fields beside them carry the human decimals.
+    # Amounts on a destination (+min_amount+) are BASE-UNIT strings (digits only, below
+    # 2^120); the +*_formatted+ fields beside them carry the human decimals. What a payout
+    # keeps back in the wallet (the refund and gas reserves) is decided at payout time, not
+    # stored on the destination: see {#reserves} and {Payouts#prepare}.
     class PayoutDestinations
       # The default of {update}'s keywords: "not passed", told apart from an explicit value.
       UNSET = Object.new.freeze
@@ -23,16 +25,13 @@ module Rail0
       include Query
 
       # The text of the gateway's +details_v1+ attestation, which +confirm_details: true+
-      # stands for on {create} and on an {update} that changes +min_amount+. Show it to the
+      # stands for on {create} and on an {update} that changes +min_amount+ or +no_minimum+. Show it to the
       # merchant and send +confirm_details: true+ only once they have accepted it.
       CONFIRM_DETAILS_TEXT =
         "I have checked the address, network, token and minimum deposit on the venue's deposit " \
         "page and confirm they are correct. Funds sent to a wrong address or network, or below " \
         "the venue's minimum, may be permanently lost and cannot be recovered by rail0."
 
-      # The venue kinds a destination can be registered as.
-      KINDS = %w[exchange circle_mint self_custody provider].freeze
-
       # A destination's statuses — the values {list}'s +status+ filter accepts.
       STATUSES = %w[unverified verified disabled].freeze
 
@@ -49,9 +48,12 @@ module Rail0
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
       # @param page [Integer, nil] Page number (1-based).
       # @param per_page [Integer, nil] Items per page (max 100).
+      # @param include_deleted [Boolean, nil] +true+ lists deleted destinations too
+      #   (+deleted_at+ set); left out by default.
       # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total:, total_pages:, links: } }
-      def list(wallet_id: nil, status: nil, sort: nil, page: nil, per_page: nil)
-        query = build_query(wallet_id: wallet_id, status: status, sort: sort, page: page, per_page: per_page)
+      def list(wallet_id: nil, status: nil, sort: nil, page: nil, per_page: nil, include_deleted: nil)
+        query = build_query(wallet_id: wallet_id, status: status, sort: sort, page: page, per_page: per_page,
+                            include_deleted: include_deleted)
         http.get_list("/payout_destinations#{query}")
       end
 
@@ -70,26 +72,45 @@ module Rail0
       # refused 422 +confirmation_required+ and nothing is saved. Pass the merchant's answer,
       # never a hard-coded +true+.
       #
+      # The venue's minimum deposit is REQUIRED too, as EXACTLY ONE of: +min_amount+, the
+      # figure the merchant read on the venue's deposit page, or +no_minimum: true+, the
+      # merchant's statement that the venue has none. Neither, a blank figure, or both raise
+      # ArgumentError here and nothing is sent (the gateway would answer 422
+      # +minimum_required+ / +minimum_conflict+). Nothing is defaulted: a minimum nobody
+      # looked up is how a deposit gets lost, so pass what the merchant answered.
+      #
+      # +label+ is REQUIRED: the name the merchant knows the destination by. The gateway
+      # trims it; it must be unique among the account's live destinations, compared without
+      # regard to case (409 +payout_destination_label_taken+ otherwise; deleting a destination
+      # frees its label). A blank or whitespace-only label raises ArgumentError here and
+      # nothing is sent (the gateway would answer 422 +label_required+).
+      #
       # @param wallet_id [String] The wallet (uuid or address) that will sign transfers to it;
       #   must be the session's own.
       # @param chain_id [Integer] The chain the deposit address was issued for.
       # @param token [String] The token's address on that chain.
       # @param address [String] The deposit address, generated at the venue WITH THE NETWORK
       #   SET TO THIS CHAIN.
+      # @param label [String] The destination's name, unique per account (case-insensitive).
       # @param confirm_details [Boolean] The merchant's acceptance of {CONFIRM_DETAILS_TEXT}.
-      # @param label [String, nil] A name for the destination.
-      # @param kind [String, nil] One of {KINDS}; the gateway defaults to "exchange".
-      # @param reserve_amount [String, nil] Base units to keep in the wallet on a full-balance
-      #   ("all") payout; omitted, the gateway's suggestion (the refundable balance still
-      #   inside its refund window) applies.
-      # @param min_amount [String, nil] The venue's deposit minimum in base units; omitted, none.
-      #   A payout below it is refused (+payout_below_minimum+) and the proof is raised to it.
+      # @param min_amount [String, nil] The venue's deposit minimum in base units. A payout
+      #   below it is refused (+payout_below_minimum+) and the proof is raised to it.
+      # @param no_minimum [Boolean] +true+: the merchant states the venue has no minimum.
       # @return [Hash] The destination.
-      def create(wallet_id:, chain_id:, token:, address:, confirm_details:, label: nil, kind: nil,
-                 reserve_amount: nil, min_amount: nil)
+      # @raise [ArgumentError] when +label+ is blank, when neither or both of +min_amount+ /
+      #   +no_minimum: true+ are given, or +min_amount+ is blank.
+      def create(wallet_id:, chain_id:, token:, address:, label:, confirm_details:, min_amount: nil,
+                 no_minimum: false)
+        check_label!(label)
+        figure = !min_amount.nil? && !min_amount.to_s.strip.empty?
+        if figure == (no_minimum == true)
+          raise ArgumentError, "exactly one of min_amount (the venue's minimum, base units) or no_minimum: true " \
+                               "is required"
+        end
+
         body = { wallet_id: wallet_id, chain_id: chain_id, token: token, address: address,
-                 confirm_details: confirm_details, label: label, kind: kind,
-                 reserve_amount: reserve_amount, min_amount: min_amount }.compact
+                 confirm_details: confirm_details, label: label, min_amount: min_amount,
+                 no_minimum: (true if no_minimum == true) }.compact
         http.post("/payout_destinations", body)
       end
 
@@ -103,9 +124,15 @@ module Rail0
       # Update a destination. Only the keywords you PASS are sent, and at least one is
       # required (ArgumentError otherwise).
       #
-      # - +reserve_amount+ / +min_amount+: base units; an empty string restores the suggestion
-      #   (reserve) or removes the minimum.
-      # - A request that CHANGES +min_amount+ also needs +confirm_details: true+ — the same
+      # - +label+: renames it. Never blank (ArgumentError here, 422 +label_required+ at the
+      #   gateway) and unique among the account's live destinations, case-insensitive (409
+      #   +payout_destination_label_taken+).
+      # - +min_amount+: the venue's minimum, base units (+"0"+ is a figure like any other); it
+      #   also clears +no_minimum+. Never blank: an empty string raises ArgumentError here.
+      # - +no_minimum: true+: the venue has no minimum — how a minimum is removed (+min_amount+
+      #   becomes nil). Never together with +min_amount+ (ArgumentError here, 422
+      #   +minimum_conflict+ at the gateway).
+      # - A request that CHANGES +min_amount+ or +no_minimum+ also needs +confirm_details: true+ — the same
       #   attestation as {create} ({CONFIRM_DETAILS_TEXT}), else 422 +confirmation_required+
       #   and nothing is written. Raising the minimum above the destination's latest proof
       #   takes its verification away: prove it again with a new proof.
@@ -115,17 +142,53 @@ module Rail0
       #
       # @param id [String] Destination uuid.
       # @return [Hash] The destination.
-      def update(id, label: UNSET, reserve_amount: UNSET, min_amount: UNSET, active: UNSET,
-                 confirm_details: UNSET)
-        body = { label: label, reserve_amount: reserve_amount, min_amount: min_amount, active: active,
+      def update(id, label: UNSET, min_amount: UNSET, no_minimum: UNSET, active: UNSET, confirm_details: UNSET)
+        body = { label: label, min_amount: min_amount, no_minimum: no_minimum, active: active,
                  confirm_details: confirm_details }.reject { |_, v| v.equal?(UNSET) }
         if body.except(:confirm_details).empty?
-          raise ArgumentError, "at least one of label, reserve_amount, min_amount or active is required"
+          raise ArgumentError, "at least one of label, min_amount, no_minimum or active is required"
         end
 
+        check_label!(body[:label]) if body.key?(:label)
+        check_minimum!(body)
+
         http.patch("/payout_destinations/#{segment(id)}", body)
       end
 
+      # Delete a destination (soft): it leaves the lists ({list} shows it again with
+      # +include_deleted: true+), and its payment method and its label are free to be
+      # registered again. The row is
+      # kept — its payouts and audit trail still name it, and {get} / {events} still read it
+      # with +deleted_at+ set and +status+ "disabled". Its pending payout is settled first, as
+      # on a switch-off: an unsigned one is cancelled, a signed one refuses the delete 409
+      # +payout_already_signed+. Only the destination's own wallet may delete it; a deleted
+      # destination takes no further write (404). Recorded as +destination.deleted+.
+      # @param id [String] Destination uuid.
+      # @return [Hash] The destination as it now stands.
+      def delete(id)
+        http.delete("/payout_destinations/#{segment(id)}")
+      end
+
+      # What a payout to the destination would keep back in the wallet right now, computed
+      # from the wallet's payments and the chain's current fees (nothing is stored):
+      #
+      # - +refund_reserve+: the refundable balance of the wallet's payments in this token
+      #   still inside their refund window (+refundable_payments+ of them).
+      # - +gas_reserve+: on a chain whose gas IS this token (+native_gas+, Arc's USDC), the gas
+      #   for those refunds and for capturing the open authorizations plus +base_captures+
+      #   more; "0" elsewhere.
+      # - +gas_allowance+: the payout transfer's own fee, always kept back on a native-gas chain.
+      # - +available+: what +amount: "all"+ moves with both reserves kept (the default).
+      #
+      # Every amount is base units with its +*_formatted+ twin. Both reserves can be opted
+      # out of per payout ({Payouts#prepare}'s +keep_refund_reserve:+ / +keep_gas_reserve:+).
+      # Any wallet of the account may read it; a deleted destination still reads.
+      # @param id [String] Destination uuid.
+      # @return [Hash] The reserves (see Rail0::Types::PayoutReserves).
+      def reserves(id)
+        http.get("/payout_destinations/#{segment(id)}/reserves")
+      end
+
       # The merchant's attestation that the venue CREDITED the proof transfer: marks the
       # destination +verified+. The proof payout must be +confirmed+ on-chain first (422
       # +payout_destination_proof_missing+ otherwise).
@@ -144,6 +207,28 @@ module Rail0
       def events(id, page: nil, per_page: nil)
         http.get_list("/payout_destinations/#{segment(id)}/events#{build_query(page: page, per_page: per_page)}")
       end
+
+      private
+
+      # A destination's label is required and never blank (the gateway's +label_required+);
+      # refused here so nothing is sent.
+      def check_label!(label)
+        return unless label.to_s.strip.empty?
+
+        raise ArgumentError, "label is required and cannot be blank: name the destination"
+      end
+
+      # {update}'s local minimum checks, before anything is sent: a blank +min_amount+ is
+      # never a minimum (the gateway's +minimum_required+; +no_minimum: true+ removes one),
+      # and a figure beside +no_minimum: true+ contradicts itself (+minimum_conflict+).
+      def check_minimum!(body)
+        if body.key?(:min_amount) && body[:min_amount].to_s.strip.empty?
+          raise ArgumentError, "min_amount cannot be blank: pass the venue's minimum, or no_minimum: true to remove it"
+        end
+        return unless body.key?(:min_amount) && body[:no_minimum] == true
+
+        raise ArgumentError, "pass min_amount or no_minimum: true, not both"
+      end
     end
   end
 end

data/lib/rail0/resources/payouts.rb

@@ -20,8 +20,9 @@ module Rail0
     # +failed+, or subscribe to the +payouts.confirmed+ / +payouts.failed+ webhooks.
     #
     # Amounts: +prepare+'s +amount+ is a HUMAN decimal ("250.00") or "all" (the balance
-    # minus the destination's reserve); the payout record's +amount+ is base units, with
-    # +amount_formatted+ beside it.
+    # minus what the payout keeps back); the payout record's +amount+ is base units, with
+    # +amount_formatted+ beside it, and +refund_reserve+ / +gas_reserve+ record what it kept
+    # back (base units; nil for a proof).
     class Payouts
       include Query
 
@@ -70,17 +71,29 @@ module Rail0
       #   +min_amount+ when that is higher; +amount+ is ignored. An unverified destination
       #   may receive the proof at most.
       # - +purpose: "payout"+ (the default) sends +amount+: a human decimal, or "all" for
-      #   the balance minus the reserve. Below the destination's +min_amount+ it is refused
-      #   422 +payout_below_minimum+.
+      #   the balance minus what is kept back. Below the destination's +min_amount+ it is
+      #   refused 422 +payout_below_minimum+.
+      # - What a payout keeps back in the wallet is decided here, at payout time: the refund
+      #   reserve (the refundable balance of payments still inside their refund window) and,
+      #   on a chain whose gas is this very token (Arc's USDC), the gas reserve (gas for the
+      #   refunds and captures the wallet still owes). Both are kept by default;
+      #   +keep_refund_reserve: false+ / +keep_gas_reserve: false+ opts this payout out of one
+      #   (a refund or capture after it may then fail for lack of funds). Payout purpose only;
+      #   sent only when given. {PayoutDestinations#reserves} shows the figures beforehand.
       # - A payout that already holds a signed transaction cannot be re-prepared (409
       #   +payout_already_signed+): {resend} it, or let it settle.
       #
       # @param destination_id [String] Destination uuid.
       # @param purpose [String, nil] One of {PURPOSES}; the gateway defaults to "payout".
       # @param amount [String, nil] Human decimal or "all"; required for a payout.
+      # @param keep_refund_reserve [Boolean, nil] +false+ opts out of keeping the refund
+      #   reserve; the gateway defaults to +true+.
+      # @param keep_gas_reserve [Boolean, nil] +false+ opts out of keeping the gas reserve;
+      #   the gateway defaults to +true+.
       # @return [Hash] The pending payout.
-      def prepare(destination_id:, purpose: nil, amount: nil)
-        body = { destination_id: destination_id, purpose: purpose, amount: amount }.compact
+      def prepare(destination_id:, purpose: nil, amount: nil, keep_refund_reserve: nil, keep_gas_reserve: nil)
+        body = { destination_id: destination_id, purpose: purpose, amount: amount,
+                 keep_refund_reserve: keep_refund_reserve, keep_gas_reserve: keep_gas_reserve }.compact
         http.post("/payouts/prepare", body)
       end
 

data/lib/rail0/types.rb

@@ -47,6 +47,20 @@ module Rail0
       :decimals,  # Integer
       :raw,       # String — Balance in base units (exact).
       :amount,    # String — Human-decimal balance.
+      :payout,    # What a payout in this token keeps back for gas — on every ERC-20 line; null on the native balance.
+      keyword_init: true
+    )
+
+    # The gas figures of a payout in this token on this chain: whether the chain's gas IS this very
+    # token (`native_gas`; Arc's USDC) and, then, the allowance POST /payouts/prepare keeps back from
+    # `all`, from a typed amount's ceiling and from the proof (`gas_allowance` = gas_limit ×
+    # max_fee_per_gas in base units, the charge the EVM takes before a transfer runs; `0` on any other
+    # chain). Null allowance when the fee could not be read. The reserves a payout keeps back are
+    # decided at payout time: GET /payout_destinations/{id}/reserves.
+    BalancePayout = Struct.new(
+      :native_gas,               # Boolean
+      :gas_allowance,            # String | nil
+      :gas_allowance_formatted,  # String | nil
       keyword_init: true
     )
 
@@ -600,27 +614,51 @@ module Rail0
     )
 
     PayoutDestination = Struct.new(
-      :id,                           # String
-      :wallet_id,                    # String
-      :chain_id,                     # Integer
-      :token,                        # String — ERC-20 address on that chain, lowercased.
-      :token_symbol,                 # String | nil
-      :address,                      # String — The deposit address, lowercased.
-      :label,                        # String | nil
-      :kind,                         # String
-      :status,                       # String
-      :has_code,                     # Boolean | nil — Whether the address held code on this chain when registered (eth_getCode, best effort). An EOA and an undeployed contract look the same.
-      :reserve_amount,               # String | nil — Base units kept in the wallet on a full-balance payout; null = the suggestion.
-      :reserve_amount_formatted,     # String | nil — `reserve_amount` in human decimals (the token's decimals); null while the suggestion applies, or when the token left the catalog.
-      :suggested_reserve,            # String — Base units: the refundable balance of the wallet's payments in this token still inside their refund window.
-      :suggested_reserve_formatted,  # String | nil — `suggested_reserve` in human decimals; null when the token left the catalog.
-      :min_amount,                   # String | nil — The venue's deposit minimum, base units; null = no minimum. A payout below it is refused (`payout_below_minimum`); the proof transfer is raised to it.
-      :min_amount_formatted,         # String | nil — `min_amount` in human decimals (the token's decimals); null when there is no minimum, or when the token left the catalog.
-      :proof_payout_id,              # String | nil
-      :verified_at,                  # String | nil
-      :disabled_at,                  # String | nil
-      :created_at,                   # String
-      :updated_at,                   # String
+      :id,                    # String
+      :wallet_id,             # String
+      :chain_id,              # Integer
+      :token,                 # String — ERC-20 address on that chain, lowercased.
+      :token_symbol,          # String | nil
+      :address,               # String — The deposit address, lowercased.
+      :label,                 # String — The merchant's name for it: never blank, unique (case-insensitive) among the account's live destinations.
+      :status,                # String
+      :has_code,              # Boolean | nil — Whether the address held code on this chain when registered (eth_getCode, best effort). An EOA and an undeployed contract look the same.
+      :min_amount,            # String | nil — The venue's deposit minimum, base units; null = no minimum. A payout below it is refused (`payout_below_minimum`); the proof transfer is raised to it.
+      :no_minimum,            # Boolean — true when the merchant stated the venue has no minimum deposit (`min_amount` is then null). false with a null `min_amount`: never stated (a destination registered before it was asked).
+      :min_amount_formatted,  # String | nil — `min_amount` in human decimals (the token's decimals); null when there is no minimum, or when the token left the catalog.
+      :proof_payout_id,       # String | nil
+      :verified_at,           # String | nil
+      :disabled_at,           # String | nil
+      :deleted_at,            # String | nil — When the merchant deleted it (DELETE /payout_destinations/{id}); null for a live destination.
+      :created_at,            # String
+      :updated_at,            # String
+      keyword_init: true
+    )
+
+    # What a payout to the destination would keep back right now (GET
+    # /payout_destinations/{id}/reserves). Every amount is base units as a string, with its
+    # human-decimals twin (`*_formatted`, the token's decimals).
+    PayoutReserves = Struct.new(
+      :destination_id,            # String
+      :chain_id,                  # Integer
+      :token,                     # String — ERC-20 address on that chain, lowercased.
+      :token_symbol,              # String
+      :decimals,                  # Integer
+      :balance,                   # String — The wallet's balance of the token, read now.
+      :balance_formatted,         # String
+      :refund_reserve,            # String — The refundable balance of the wallet's payments in this token still inside their refund window.
+      :refund_reserve_formatted,  # String
+      :refundable_payments,       # Integer — How many payments `refund_reserve` covers: the refunds the wallet may still owe.
+      :native_gas,                # Boolean — Whether the chain's gas is paid in this very token (Arc's USDC). The gas figures are `0` when it is not.
+      :gas_reserve,               # String — Gas for `gas_refunds` refunds and for `open_authorizations` + `base_captures` captures, at their gas limits and the fee ceiling a prepare would set now; `0` off a native-gas chain. Counted over every token of the chain: on Arc a EURC payment's capture or refund is paid in USDC gas too.
+      :gas_reserve_formatted,     # String
+      :gas_refunds,               # Integer — The wallet's payments on this chain, in any token, still inside their refund window with something left to refund: the refunds the gas reserve pays for.
+      :open_authorizations,       # Integer — The wallet's payments on this chain, in any token, still capturable (a capture's gas is the merchant wallet's).
+      :base_captures,             # Integer — Captures the gas reserve pays for on top of the open authorizations, so the wallet can capture the payments it takes next.
+      :gas_allowance,             # String — The payout transfer's own fee (gas_limit × max_fee_per_gas), always kept back on a native-gas chain; `0` elsewhere.
+      :gas_allowance_formatted,   # String
+      :available,                 # String — balance − refund_reserve − gas_reserve − gas_allowance, floored at 0: what `amount: all` moves with both reserves kept (the default).
+      :available_formatted,       # String
       keyword_init: true
     )
 
@@ -634,13 +672,16 @@ module Rail0
       :address,               # String — The recipient.
       :amount,                # String — Base units.
       :amount_formatted,      # String — Human decimals.
+      :refund_reserve,        # String | nil — Base units this payout kept back in the wallet for refunds, decided at prepare; `0` when the merchant opted out (`keep_refund_reserve: false`); null for a proof.
+      :gas_reserve,           # String | nil — Base units this payout kept back for the gas the wallet still owes (native-gas chains only, `0` elsewhere or when opted out with `keep_gas_reserve: false`); null for a proof.
       :purpose,               # String
-      :status,                # String
+      :status,                # String — `pending` (prepared, awaiting the signature) → `submitted` (hash known; still `submitted` once mined, until its block is final) → `confirmed` | `failed`. Both outcomes are decided only once the receipt's block is at or below the chain's finality bound (its `finality_tag` block, or head − `required_confirmations` for `depth` or a node that serves no tag) and still canonical; `payouts.confirmed` / `payouts.failed` fire then.
       :unsigned_transaction,  # String | nil — JSON of the EIP-1559 transaction to sign (`to` = the token, `data` = transfer(address,uint256)). Check it against the decoded fields beside it before signing.
       :signed,                # Boolean — Whether the gateway stores the wallet's signed transaction (the payload itself is never exposed). A `pending` payout with `signed: true` already has its `transaction_hash` and may be in a mempool: resend it (POST /payouts/{id}/resend); it cannot be re-prepared.
       :transaction_hash,      # String | nil — Keccak of the signed transaction, stored with it on submit (so a signed `pending` row has it too), or the hash the wallet reported.
       :sender,                # String | nil
-      :block_number,          # Integer | nil
+      :block_number,          # Integer | nil — The receipt's block. Set when the gateway first sees the receipt (the payout stays `submitted` until that block is final) moved to the new block if a reorg re-includes the transaction elsewhere, and cleared only while no block holds it.
+      :mined_at,              # String | nil — When the gateway first saw the receipt (its own clock, not the block's timestamp). Non-null on a `submitted` payout: mined, waiting for finality.
       :gas_used,              # String | nil
       :error_code,            # String | nil — When failed: `reverted` (mined, status 0), `foreign_transfer` (mined, but the receipt has no Transfer of this amount of this token from the wallet to this destination), `dropped` (not mined, and the wallet's confirmed nonce has passed the signed transaction's), `submission_timeout` (a reported hash no node has ever known, past SUBMITTED_TX_TTL), `cancelled` (unsigned, cancelled by the merchant with POST /payouts/{id}/cancel or by disabling its destination). `submission_timeout` and `dropped` are not final: POST /payouts/{id}/submitted with a late hash puts the payout back to `submitted`.
       :error_title,           # String | nil

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.9.0"
+  VERSION = "1.10.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-30 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger