rail0-sdk 1.8.1 → 1.10.0

data/lib/rail0/resources/chains.rb

@@ -18,7 +18,9 @@ module Rail0
       # List active blockchains supported by RAIL0.
       # @param network_type [String, nil] Filter by "testnet" or "mainnet".
       # @param symbol [String, nil] Filter by native symbol (case-insensitive, e.g. "ETH").
-      # @return [Array<Hash>] chain_id, name, native_symbol, network_type, explorer_url,
+      # @return [Array<Hash>] chain_id, slug (shared by a chain's testnet and mainnet, e.g.
+      #   "arc"; unique per network_type), name, native_symbol, network_type, explorer_url,
+      #   public_rpc_urls (keyless RPC endpoints published for clients),
       #   required_confirmations, finality_tag (the settlement rule: the tag where the
       #   chain serves one, the count only where it does not), and contract — the chain's
       #   active RAIL0 deployment as `{ address:, version:, deployed_at: }` (what holds
@@ -32,6 +34,54 @@ module Rail0
       def list(network_type: nil, symbol: nil)
         http.get("/blockchains#{build_query(network_type: network_type, symbol: symbol)}")
       end
+
+      # Picks one chain out of a {list} result by numeric chain id OR slug. No request.
+      #
+      # +ref+ is an Integer or an all-digit String (a chain id: "5042002", 5042002) or a
+      # slug, compared case-insensitively ("Arc"). A slug is shared by a chain's testnet
+      # and mainnet, so when the list holds both it is AMBIGUOUS and raises rather than
+      # guessing which network the caller meant: pass the chain id, or a list filtered
+      # with +network_type:+. Nothing matching raises too, naming the slugs available.
+      #
+      #   chains = client.chains.list(network_type: "testnet")
+      #   Rail0::Resources::Chains.resolve(chains, "arc")    # => { chain_id: 5042002, slug: "arc", ... }
+      #   Rail0::Resources::Chains.resolve(chains, 5042002)  # the same chain
+      #
+      # @param chains [Array<Hash>] blockchains, as {list} returns them (symbol or string keys)
+      # @param ref [Integer, String] chain id or slug
+      # @return [Hash] the matching chain
+      # @raise [ArgumentError] when nothing matches, or the slug matches several chains
+      def self.resolve(chains, ref)
+        key = ref.to_s.strip
+        raise ArgumentError, "a chain id or slug is required" if key.empty?
+
+        rows = Array(chains).map { |c| c.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k } }
+        return resolve_id(rows, key) if key.match?(/\A\d+\z/)
+
+        matches = rows.select { |c| c[:slug].to_s.casecmp(key).zero? }
+        return matches.first if matches.size == 1
+
+        if matches.empty?
+          raise ArgumentError, "no chain with slug #{key.inspect} (available slugs: #{describe_available(rows)})"
+        end
+
+        ids = matches.map { |c| "#{c[:chain_id]} (#{c[:network_type] || 'unknown network'})" }.join(", ")
+        raise ArgumentError, "slug #{key.inspect} is ambiguous: it matches chains #{ids} — pass the chain id, " \
+                             "or list with network_type:"
+      end
+
+      def self.resolve_id(rows, key)
+        found = rows.find { |c| c[:chain_id].to_s == key.sub(/\A0+(?=\d)/, "") }
+        return found if found
+
+        raise ArgumentError, "no chain with id #{key} (available: #{describe_available(rows)})"
+      end
+
+      def self.describe_available(rows)
+        slugs = rows.map { |c| c[:slug].to_s.downcase }.reject(&:empty?).uniq.sort
+        slugs.empty? ? "none" : slugs.join(", ")
+      end
+      private_class_method :resolve_id, :describe_available
     end
   end
 end

data/lib/rail0/resources/payments.rb

@@ -74,7 +74,12 @@ module Rail0
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
       # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
-      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total: } }. Each row
+      # @param after [String, nil] Cursor paging: the previous page's `meta[:next_cursor]`.
+      #   Walks newest first at a constant cost per page, with no total (`total` reads 0);
+      #   `page:` and any `sort:` other than "-created_at" beside it are 422 `invalid_cursor`.
+      #   Omit it on the first page (pass `per_page:` alone) and follow `next_cursor` until nil.
+      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total:, total_pages:, links:,
+      #   next_cursor: } }. Each row
       #   carries, besides the payment fields, `chain_id`, `decimals` (Integer, or nil when
       #   the gateway can't resolve the token — fall back to {Tokens#list} then) to render the
       #   base-unit amounts without a token lookup, and `in_flight` (Boolean: a transaction is
@@ -84,7 +89,7 @@ module Rail0
                chain_id: nil, disputed: nil, operation: nil, min_amount: nil, max_amount: nil,
                created_from: nil, created_to: nil, scope: nil, account_id: nil, has_error: nil,
                expiring_within: nil, reference: nil, reference_origin: nil, sort: nil, page: nil,
-               per_page: nil)
+               per_page: nil, after: nil)
         query = build_query(status: status, mode: mode, payer: payer, payee: payee, token: token,
                             rail0_id: rail0_id, reference: reference, reference_origin: reference_origin,
                             chain_id: chain_id, disputed: disputed,
@@ -93,7 +98,7 @@ module Rail0
                             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)
+                            sort: sort, page: page, per_page: per_page, after: after)
         http.get_list("/payments#{query}")
       end
 

data/lib/rail0/resources/payout_destinations.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Payout destinations: where a merchant wallet sends its balance — a deposit address at
+    # an exchange, Circle Mint, an off-ramp provider or the merchant's own custody (JWT,
+    # merchant session).
+    #
+    # A destination is registered +unverified+. It becomes +verified+ after a small PROOF
+    # transfer ({Payouts#prepare} with +purpose: "proof"+) has confirmed on-chain AND the
+    # 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 (+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
+      private_constant :UNSET
+
+      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+ 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."
+
+      # A destination's statuses — the values {list}'s +status+ filter accepts.
+      STATUSES = %w[unverified verified disabled].freeze
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List the account's payout destinations (every wallet of the account).
+      # @param wallet_id [String, nil] Only this wallet's destinations (uuid).
+      # @param status [String, nil] One of {STATUSES}.
+      # @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, 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
+
+      # Register a payout destination for the session's own wallet. Answers 201 with the
+      # destination, +unverified+.
+      #
+      # +confirm_details+ is REQUIRED and has no default on purpose: +true+ is the merchant's
+      # attestation of {CONFIRM_DETAILS_TEXT} (the gateway's +details_v1+) —
+      #
+      #   "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."
+      #
+      # — recorded with who and when in the +destination.created+ event. Anything but +true+ is
+      # 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 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.
+      # @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, min_amount: min_amount,
+                 no_minimum: (true if no_minimum == true) }.compact
+        http.post("/payout_destinations", body)
+      end
+
+      # Read one destination (any wallet of the account may).
+      # @param id [String] Destination uuid.
+      # @return [Hash]
+      def get(id)
+        http.get("/payout_destinations/#{segment(id)}")
+      end
+
+      # Update a destination. Only the keywords you PASS are sent, and at least one is
+      # required (ArgumentError otherwise).
+      #
+      # - +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.
+      # - +active: false+ disables it (any wallet of the account may); its unsigned pending
+      #   payout is cancelled, a signed one refuses the switch-off 409 +payout_already_signed+.
+      #   +active: true+ re-enables it with the verification it had.
+      #
+      # @param id [String] Destination uuid.
+      # @return [Hash] The destination.
+      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, 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).
+      # @param id [String] Destination uuid.
+      # @return [Hash] The destination, now verified.
+      def confirm(id)
+        http.post("/payout_destinations/#{segment(id)}/confirm")
+      end
+
+      # The destination's audit trail, newest first: its own events and those of every
+      # payout made to it (+destination.created+, +payout.prepared+, +payout.confirmed+, …).
+      # @param id [String] Destination uuid.
+      # @param page [Integer, nil] Page number (1-based).
+      # @param per_page [Integer, nil] Items per page (default 25, max 100).
+      # @return [Hash] { data: Array<Hash>, meta: { ... } }
+      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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "query"
+
+module Rail0
+  module Resources
+    # Merchant payouts: an ERC-20 transfer of the wallet's balance to one of its
+    # {PayoutDestinations} (JWT, merchant session; the destination's own wallet signs).
+    #
+    # Two-phase like the payment operations. {prepare} builds the unsigned EIP-1559
+    # transaction — a +transfer(address,uint256)+ on the TOKEN contract — and answers the
+    # pending payout with it in +unsigned_transaction+. Then either:
+    #
+    # - sign it offline and {submit} the raw bytes (the gateway broadcasts them) — or do
+    #   both with {sign_and_submit}, which VERIFIES the transaction before signing; or
+    # - broadcast it yourself (a wallet that signs and sends in one step) and report the
+    #   hash with {submit_by_hash}.
+    #
+    # The payout then settles asynchronously: poll {get} until +status+ is +confirmed+ or
+    # +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 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
+
+      # What a payout is for: "proof" (the small test transfer that verifies a
+      # destination) or "payout" (the default).
+      PURPOSES = %w[payout proof].freeze
+
+      # A payout's statuses — the values {list}'s +status+ filter accepts.
+      STATUSES = %w[pending submitted confirmed failed].freeze
+
+      attr_reader :http
+
+      def initialize(http)
+        @http = http
+        freeze
+      end
+
+      # List the account's payouts, newest first by default.
+      # @param destination_id [String, nil] Only payouts to this destination (uuid).
+      # @param wallet_id [String, nil] Only this wallet's payouts (uuid).
+      # @param status [String, Array<String>, nil] One of {STATUSES}, or an Array matching
+      #   ANY of them (sent comma-separated).
+      # @param purpose [String, nil] One of {PURPOSES}.
+      # @param created_from [String, nil] Only payouts created at/after this ISO-8601 time.
+      # @param created_to [String, nil] Only payouts created at/before this ISO-8601 time.
+      # @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 (default 25, max 100).
+      # @param after [String, nil] Cursor paging, as on {Payments#list}: the previous page's
+      #   `meta[:next_cursor]`; no total, and not combinable with `page:` or another sort.
+      # @return [Hash] { data: Array<Hash>, meta: { page:, per_page:, total:, total_pages:, links:,
+      #   next_cursor: } }
+      def list(destination_id: nil, wallet_id: nil, status: nil, purpose: nil, created_from: nil,
+               created_to: nil, sort: nil, page: nil, per_page: nil, after: nil)
+        query = build_query(destination_id: destination_id, wallet_id: wallet_id, status: status,
+                            purpose: purpose, created_from: created_from, created_to: created_to,
+                            sort: sort, page: page, per_page: per_page, after: after)
+        http.get_list("/payouts#{query}")
+      end
+
+      # Prepare a transfer to a destination (POST /payouts/prepare): 201 with a new pending
+      # payout, or 200 re-preparing the destination's unsigned pending one (one pending
+      # payout per destination). Its +unsigned_transaction+ is what to sign.
+      #
+      # - +purpose: "proof"+ sends the gateway's proof amount, raised to the destination's
+      #   +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 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, 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
+
+      # Read one payout.
+      # @param id [String] Payout uuid.
+      # @return [Hash]
+      def get(id)
+        http.get("/payouts/#{segment(id)}")
+      end
+
+      # The payout's audit trail, newest first.
+      # @param id [String] Payout uuid.
+      # @param page [Integer, nil] Page number (1-based).
+      # @param per_page [Integer, nil] Items per page (default 25, max 100).
+      # @return [Hash] { data: Array<Hash>, meta: { ... } }
+      def events(id, page: nil, per_page: nil)
+        http.get_list("/payouts/#{segment(id)}/events#{build_query(page: page, per_page: per_page)}")
+      end
+
+      # Submit the signed transfer; the gateway stores it, then broadcasts it (HTTP 202,
+      # now +submitted+). A node refusal answers 502 and leaves the payout +pending+ with
+      # its signature: {resend} it. Prefer {sign_and_submit}, which verifies before signing.
+      # @param id [String] Payout uuid.
+      # @param params [Hash] { signed_transaction: "0x…" }.
+      # @return [Hash] The payout.
+      def submit(id, params)
+        http.post("/payouts/#{segment(id)}/submit", params)
+      end
+
+      # Verify, sign and submit a prepared payout in one call.
+      #
+      # {Rail0::Signing.sign_payout} first holds the +unsigned_transaction+ to the payout —
+      # +to+ the token, value 0, the payout's chain, calldata exactly
+      # +transfer(destination address, payout amount)+, nothing trailing — and, when given,
+      # to the registered +destination:+ and to the +amount:+ you asked prepare for (scaled
+      # by +decimals:+). Anything else raises {Rail0::TxVerify::RefusedSignature} and
+      # nothing is signed or sent. Then {submit}.
+      #
+      #   destination = client.payout_destinations.get(destination_id)
+      #   payout = client.payouts.prepare(destination_id: destination_id, amount: "250.00")
+      #   client.payouts.sign_and_submit(payout, MERCHANT_PRIVATE_KEY, destination: destination,
+      #                                  amount: "250.00", decimals: 6)
+      #
+      # Needs the optional +eth+ gem (loaded here, not by +require "rail0"+).
+      #
+      # @param payout [Hash] The prepared payout (from {prepare} or {get}).
+      # @param private_key [String, Eth::Key] The destination wallet's key.
+      # @param destination [Hash, nil] The destination the payout must be for.
+      # @param amount [String, nil] The human decimal passed to prepare (not "all").
+      # @param decimals [Integer, nil] The token's decimals, required with +amount:+.
+      # @return [Hash] The payout, now +submitted+.
+      def sign_and_submit(payout, private_key, destination: nil, amount: nil, decimals: nil)
+        require_relative "../signing"
+
+        raw = Rail0::Signing.sign_payout(payout, private_key, destination: destination,
+                                                              amount: amount, decimals: decimals)
+        submit(payout[:id] || payout["id"], { signed_transaction: raw })
+      end
+
+      # Re-broadcast the signed transaction a {submit} stored (no body): the same bytes, so
+      # the same nonce and hash. For a submit whose broadcast was refused or went
+      # unanswered (422 +payout_not_signed+ when there is nothing to resend).
+      # @param id [String] Payout uuid.
+      # @return [Hash] The payout.
+      def resend(id)
+        http.post("/payouts/#{segment(id)}/resend")
+      end
+
+      # Cancel an UNSIGNED pending payout: it becomes +failed+ with +error_code+ "cancelled"
+      # and the destination is free for a new prepare. A signed one is refused 409
+      # +payout_already_signed+ — its transaction may still be mined.
+      # @param id [String] Payout uuid.
+      # @return [Hash] The payout.
+      def cancel(id)
+        http.post("/payouts/#{segment(id)}/cancel")
+      end
+
+      # Report a transfer the wallet broadcast itself, by hash (POST /payouts/{id}/submitted,
+      # HTTP 202). The hash must be THIS transfer — from the wallet, on the token, this amount
+      # to this destination — or 422 +foreign_transfer_hash+. Also accepts a LATE hash on a
+      # payout that failed +submission_timeout+ or +dropped+.
+      # @param id [String] Payout uuid.
+      # @param params [Hash] { transaction_hash: "0x…" }.
+      # @return [Hash] The payout, now +submitted+.
+      def submit_by_hash(id, params)
+        http.post("/payouts/#{segment(id)}/submitted", params)
+      end
+    end
+  end
+end

data/lib/rail0/resources/webhooks.rb

@@ -16,6 +16,10 @@ module Rail0
       include Query
 
       # Event topics a subscription can carry. It may carry any non-empty subset.
+      # The payout topics deliver the same envelope ({id, emitted_at, topic}) with the
+      # subject under its own key: +payout+ for payouts.confirmed / payouts.failed (a
+      # failure's reason is its +error_code+), +payout_destination+ for
+      # payout_destinations.verified.
       TOPICS = %w[
         payments.created
         payments.signed
@@ -30,6 +34,9 @@ module Rail0
         payments.failed
         payments.disputed
         payments.dispute_closed
+        payouts.confirmed
+        payouts.failed
+        payout_destinations.verified
       ].freeze
 
       attr_reader :http

data/lib/rail0/signing.rb

@@ -15,6 +15,7 @@ end
 
 require_relative "tx_verify"
 require_relative "payload_verify"
+require_relative "payout_verify"
 
 module Rail0
   # EIP-712 and EIP-3009 signing utilities for RAIL0 payments.
@@ -277,6 +278,49 @@ module Rail0
              "so it is verified first", uplevel: 1, category: :deprecated)
       end
 
+      assemble_and_sign(unsigned_transaction, key)
+    end
+
+    # Verify, then sign, a prepared payout's +unsigned_transaction+ — the ERC-20
+    # +transfer(address,uint256)+ that moves the merchant's balance to a payout
+    # destination — and return the signed raw transaction for {Resources::Payouts#submit}.
+    #
+    # Before the key touches it, {Rail0::PayoutVerify.verify} holds the transaction to the
+    # payout: value 0, the payout's chain, +to+ = the payout's token, the key's own address
+    # as +from+, and calldata EXACTLY +transfer(payout.address, payout.amount)+ with nothing
+    # trailing. With +destination:+ the payout must also be for that registered destination
+    # (chain, token, address); with +amount:+ (the human decimal you asked prepare for) and
+    # +decimals:+ its amount must be exactly that. A mismatch raises
+    # {Rail0::TxVerify::RefusedSignature} naming the field, and nothing is signed. There is
+    # no blind form.
+    #
+    #   destination = client.payout_destinations.get(destination_id)
+    #   payout = client.payouts.prepare(destination_id: destination_id, amount: "250.00")
+    #   raw = Rail0::Signing.sign_payout(payout, MERCHANT_PRIVATE_KEY, destination: destination,
+    #                                    amount: "250.00", decimals: 6)
+    #   client.payouts.submit(payout[:id], signed_transaction: raw)
+    #
+    # {Resources::Payouts#sign_and_submit} does the last two steps in one call.
+    #
+    # @param payout [Hash] the prepared payout (from +payouts.prepare+ or +payouts.get+)
+    # @param private_key [String, Eth::Key] the destination wallet's key
+    # @param destination [Hash, nil] the registered destination the payout must be for
+    # @param amount [String, nil] the human decimal passed to prepare (not "all")
+    # @param decimals [Integer, nil] the token's decimals, required with +amount:+
+    # @return [String] 0x-prefixed RLP-encoded signed transaction
+    def self.sign_payout(payout, private_key, destination: nil, amount: nil, decimals: nil)
+      key = private_key.is_a?(Eth::Key) ? private_key : Eth::Key.new(priv: private_key.delete_prefix("0x"))
+      unsigned = payout.is_a?(Hash) ? (payout[:unsigned_transaction] || payout["unsigned_transaction"]) : nil
+      tx = PayoutVerify.verify(unsigned, payout: payout, destination: destination, amount: amount,
+                                         decimals: decimals, signer: key.address.to_s)
+      assemble_and_sign(tx, key)
+    end
+
+    # Assembles the EIP-1559 transaction from the gateway's field-set and signs it with
+    # +key+ (an Eth::Key). Shared by {sign_transaction} and {sign_payout}, AFTER their
+    # checks: the field-set has already been verified, or deliberately not (the deprecated
+    # blind form).
+    def self.assemble_and_sign(unsigned_transaction, key)
       f = unsigned_transaction.is_a?(String) ? JSON.parse(unsigned_transaction) : unsigned_transaction
       f = f.transform_keys(&:to_s)
 
@@ -309,6 +353,8 @@ module Rail0
       "0x#{tx.hex}"
     end
 
+    private_class_method :assemble_and_sign
+
     # Verify, then sign, the EIP-3009 +signing_payload+ of a create, get or refund
     # prepare response. The checked form — prefer it over the bare {sign_payload}.
     #

data/lib/rail0/tx_verify.rb

@@ -185,7 +185,8 @@ module Rail0
 
     # The encodings a zero native value legitimately arrives in — absent, nil, the
     # number 0, or the string "0" / "0x0". A whitelist, deliberately: anything
-    # unrecognised must refuse the signature rather than be guessed at.
+    # unrecognised must refuse the signature rather than be guessed at. Public because
+    # {Rail0::PayoutVerify} holds a payout transfer to the same rule.
     def self.zero_native_value?(value)
       case value
       when nil then true
@@ -201,7 +202,7 @@ module Rail0
       left.to_s.casecmp(right.to_s).zero?
     end
 
-    private_class_method :refuse, :zero_native_value?, :same_address?
+    private_class_method :refuse, :same_address?
 
     # Scales the human amount the CALLER typed by the payment's token decimals, for
     # comparison against the calldata. nil when the operation takes no amount. For one