rail0-sdk 1.8.1 → 1.9.0

data/lib/rail0/resources/payout_destinations.rb

@@ -0,0 +1,149 @@
+# 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 (+reserve_amount+, +min_amount+) are BASE-UNIT strings (digits
+    # only, below 2^120); the +*_formatted+ fields beside them carry the human decimals.
+    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+. 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
+
+      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).
+      # @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)
+        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+.
+      #
+      # @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 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.
+      # @return [Hash] The destination.
+      def create(wallet_id:, chain_id:, token:, address:, confirm_details:, label: nil, kind: nil,
+                 reserve_amount: nil, min_amount: nil)
+        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
+        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).
+      #
+      # - +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
+      #   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, reserve_amount: UNSET, min_amount: UNSET, active: UNSET,
+                 confirm_details: UNSET)
+        body = { label: label, reserve_amount: reserve_amount, min_amount: min_amount, 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"
+        end
+
+        http.patch("/payout_destinations/#{segment(id)}", body)
+      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
+    end
+  end
+end

data/lib/rail0/resources/payouts.rb

@@ -0,0 +1,173 @@
+# 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 the destination's reserve); the payout record's +amount+ is base units, with
+    # +amount_formatted+ beside it.
+    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 the reserve. Below the destination's +min_amount+ it is refused
+      #   422 +payout_below_minimum+.
+      # - 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.
+      # @return [Hash] The pending payout.
+      def prepare(destination_id:, purpose: nil, amount: nil)
+        body = { destination_id: destination_id, purpose: purpose, amount: amount }.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