rails-crypto-payment 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3dbe29bd6b1411bb17d8a0d3862169736a663f69ad3f899a8f1f871994fd4903
+  data.tar.gz: 246d0ccab0c059f4a9cd9ece86fb60edfc897f3073404e7c151a48328c834dec
+SHA512:
+  metadata.gz: 6bad088f7a69036c8c0ae6b090c31563487cf731cea777c4aed3a3776c5dbde30b62038e6a130cb2a626d194f45a9f7f184d0d6988571797f678089c3e4595e9
+  data.tar.gz: 239495c620c9dbac8b6987ae694dbde16e66caa50383534db278e17dcc0ae27fd73e7557e72aec6b0322343596c5ceebc14be71489f613dd0cef8ee5f36dde10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Azmi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,51 @@
+# rails-crypto-payment
+
+Standalone Ruby library for exact USDT payment amounts and deposit retrieval. No Rails or database dependency. Host application owns credentials, wallet configuration, payment records, polling cursor, expiration, settlement, transaction locking, and jobs.
+
+Install dependencies with `bundle install`. Build release with `gem build rails-crypto-payment.gemspec`. Malformed Bybit result data raises `RailsCryptoPayment::Error`, like transport and API failures.
+
+```ruby
+require "rails_crypto_payment"
+
+base = RailsCryptoPayment.base_amount(idr: 50_000, rate: "16000") # BigDecimal("3.13")
+reserved = RailsCryptoPayment.available_codes(base: base, reserved_amounts: ["3.130001"])
+code = reserved.sample(random: Random::DEFAULT)
+amount = RailsCryptoPayment.amount(base: base, code: code) # exact six-decimal BigDecimal
+# Persist reservation under database uniqueness constraint; retry another code on conflict.
+```
+
+`base_amount` rounds quotient upward to two decimals; codes 1..9999 add increments of 0.000001 USDT. `available_codes` excludes only exact amount matches within this range. Application must scope reserved amounts by payment gateway and enforce uniqueness atomically.
+
+## EVM transfers (BSC, Plasma, testnets)
+
+```ruby
+rpc = RailsCryptoPayment::EvmRpc.new(url: "https://rpc.example", username: ENV["RPC_USER"], password: ENV["RPC_PASS"])
+latest = Integer(rpc.call("eth_blockNumber", []), 16)
+logs = rpc.transfer_logs(from_block: latest - 100, to_block: latest - 12,
+  token: "0x55d398326f99059ff775485246999027b3197955", wallets: ["0xYourWallet"])
+logs.each do |log|
+  next unless rpc.valid_transfer?(log: log, token: "0x55d398326f99059ff775485246999027b3197955")
+  amount = rpc.transfer_amount(log, decimals: 18)
+  time = rpc.block_time(log)
+  # Match recipient ("0x#{log.fetch('topics').fetch(2).last(40)}"), amount, time and gateway
+  # against an unpaid reservation before transactional settlement.
+end
+```
+
+`transfer_logs` filters token, ERC-20 Transfer topic and recipient wallets. RPC `-32005` range errors split block ranges; single-block errors propagate. `valid_transfer?` confirms successful transaction receipt and matching log. `transfer_amount` uses token decimals (BSC USDT uses 18; app test tokens may use 6). Credentialed RPC requires HTTPS. Transport, HTTP, and malformed-response failures raise `RailsCryptoPayment::Error`; JSON-RPC failures raise `RailsCryptoPayment::EvmRpc::RpcError` with `code`.
+
+## Exchange internal deposits
+
+```ruby
+binance = RailsCryptoPayment::BinanceDepositClient.new(key: ENV.fetch("BINANCE_KEY"), secret: ENV.fetch("BINANCE_SECRET"))
+row = binance.find_internal_usdt(tx_id: submitted_reference, start_time: from_ms, end_time: to_ms)
+# Check row status, coin, amount and timestamp against reservation before settlement.
+
+bybit = RailsCryptoPayment::BybitDepositClient.new(key: ENV.fetch("BYBIT_KEY"), secret: ENV.fetch("BYBIT_SECRET"))
+rows = bybit.internal_deposits(start_time: from_ms)
+# Check each row status, coin, amount and timestamp against unpaid reservations.
+```
+
+Binance returns matching internal-transfer deposit or `nil`; Bybit paginates and returns all rows. Clients sign requests with provided credentials, never read Rails credentials. Transport, HTTP, malformed-response, and API failures raise `RailsCryptoPayment::Error`.
+
+Run all focused checks with `bundle exec ruby -Ilib:test -e 'Dir["test/*_test.rb"].each { |file| require_relative file }'`.

data/lib/rails_crypto_payment/evm_rpc.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module RailsCryptoPayment
+  class EvmRpc
+    TRANSFER = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
+
+    class RpcError < Error
+      attr_reader :code
+
+      def initialize(code, message)
+        @code = code
+        super("RPC error #{code}: #{message}")
+      end
+    end
+
+    def initialize(url:, username: nil, password: nil)
+      @uri = URI(url.to_s)
+      raise ArgumentError, "RPC URL must use HTTP or HTTPS" unless %w[http https].include?(@uri.scheme)
+      raise ArgumentError, "RPC username and password must be provided together" if username.to_s.empty? != password.to_s.empty?
+      raise ArgumentError, "Credentialed RPC URL must use HTTPS" if @uri.scheme != "https" && !username.to_s.empty?
+
+      @username = username
+      @password = password
+    end
+
+    def call(method, params)
+      request = Net::HTTP::Post.new(@uri, "Content-Type" => "application/json")
+      request.basic_auth(@username, @password) if @username && @password
+      request.body = { jsonrpc: "2.0", id: 1, method: method, params: params }.to_json
+      response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == "https", open_timeout: 5, read_timeout: 15) { |http| http.request(request) }
+      raise Error, "RPC HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      body = JSON.parse(response.body)
+      raise RpcError.new(body["error"]["code"], body["error"]["message"]) if body["error"]
+
+      body.fetch("result")
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "RPC request failed: #{e.message}"
+    end
+
+    def transfer_logs(from_block:, to_block:, token:, wallets:)
+      raise ArgumentError, "from_block must not exceed to_block" if from_block > to_block
+
+      topics = wallets.map { |wallet| "0x#{wallet.delete_prefix('0x').downcase.rjust(64, '0')}" }
+      call("eth_getLogs", [{ fromBlock: "0x#{from_block.to_s(16)}", toBlock: "0x#{to_block.to_s(16)}",
+        address: token, topics: [TRANSFER, nil, topics] }])
+    rescue RpcError => e
+      raise unless e.code == -32_005 && from_block < to_block
+
+      middle = (from_block + to_block) / 2
+      transfer_logs(from_block: from_block, to_block: middle, token: token, wallets: wallets) +
+        transfer_logs(from_block: middle + 1, to_block: to_block, token: token, wallets: wallets)
+    end
+
+    def valid_transfer?(log:, token:)
+      return false if log["removed"] || !log.fetch("address").casecmp?(token) ||
+        !log.fetch("topics").first.casecmp?(TRANSFER)
+
+      receipt = call("eth_getTransactionReceipt", [log.fetch("transactionHash")])
+      receipt && receipt["status"] == "0x1" && receipt.fetch("logs").any? do |entry|
+        entry["logIndex"] == log["logIndex"] && entry.fetch("address").casecmp?(token) &&
+          entry["topics"] == log["topics"] && entry["data"] == log["data"]
+      end
+    end
+
+    def transfer_amount(log, decimals:)
+      scale = Integer(decimals)
+      raise ArgumentError, "decimals must be nonnegative" if scale.negative?
+
+      BigDecimal(Integer(log.fetch("data"), 16).to_s) / 10**scale
+    end
+
+    def block_time(log)
+      block = call("eth_getBlockByNumber", [log.fetch("blockNumber"), false])
+      Time.at(Integer(block.fetch("timestamp"), 16)).utc
+    end
+  end
+end

data/lib/rails_crypto_payment/exchange_clients.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module RailsCryptoPayment
+  class BinanceDepositClient
+    API = URI("https://api.binance.com")
+
+    def initialize(key:, secret:)
+      @key = key.to_s
+      @secret = secret.to_s
+      raise Error, "Binance API credentials missing" if @key.empty? || @secret.empty?
+    end
+
+    def find_internal_usdt(tx_id:, start_time:, end_time:)
+      params = { coin: "USDT", status: 1, startTime: start_time, endTime: end_time,
+        includeSource: true, recvWindow: 5000, timestamp: (Time.now.to_f * 1000).to_i }
+      query = URI.encode_www_form(params)
+      signature = OpenSSL::HMAC.hexdigest("SHA256", @secret, query)
+      uri = URI("#{API}/sapi/v1/capital/deposit/hisrec?#{query}&signature=#{signature}")
+      request = Net::HTTP::Get.new(uri, "X-MBX-APIKEY" => @key)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 15) { |http| http.request(request) }
+      raise Error, "Binance API HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body).find { |row| row["txId"].to_s.casecmp?(tx_id.to_s) && row["transferType"].to_i == 1 }
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "Binance API request failed: #{e.message}"
+    end
+  end
+
+  class BybitDepositClient
+    API = URI("https://api.bybit.com")
+    RECV_WINDOW = "5000"
+
+    def initialize(key:, secret:)
+      @key = key.to_s
+      @secret = secret.to_s
+      raise Error, "Bybit API credentials missing" if @key.empty? || @secret.empty?
+    end
+
+    def internal_deposits(start_time:)
+      rows = []
+      cursor = nil
+      loop do
+        params = { coin: "USDT", startTime: start_time, limit: 50 }
+        params[:cursor] = cursor unless cursor.nil? || cursor.empty?
+        result = get("/v5/asset/deposit/query-internal-record", params).fetch("result")
+        rows.concat(result.fetch("rows", []))
+        cursor = result["nextPageCursor"]
+        break if cursor.nil? || cursor.empty?
+      end
+      rows
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "Bybit API response invalid: #{e.message}"
+    end
+
+    private
+
+    def get(path, params)
+      query = URI.encode_www_form(params)
+      timestamp = (Time.now.to_f * 1000).to_i.to_s
+      signature = OpenSSL::HMAC.hexdigest("SHA256", @secret, "#{timestamp}#{@key}#{RECV_WINDOW}#{query}")
+      uri = URI("#{API}#{path}?#{query}")
+      request = Net::HTTP::Get.new(uri, "X-BAPI-API-KEY" => @key, "X-BAPI-TIMESTAMP" => timestamp,
+        "X-BAPI-RECV-WINDOW" => RECV_WINDOW, "X-BAPI-SIGN" => signature)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 5, read_timeout: 15) { |http| http.request(request) }
+      raise Error, "Bybit API HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      body = JSON.parse(response.body)
+      raise Error, "Bybit API error #{body['retCode']}: #{body['retMsg']}" unless body["retCode"] == 0
+
+      body
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "Bybit API request failed: #{e.message}"
+    end
+  end
+end

data/lib/rails_crypto_payment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module RailsCryptoPayment
+  class Error < StandardError; end
+
+  MAX_UNIQUE_CODE = 9999
+  CODE_UNIT = BigDecimal("0.000001")
+
+  def self.base_amount(idr:, rate:)
+    exchange_rate = BigDecimal(rate.to_s)
+    raise ArgumentError, "rate must be positive" unless exchange_rate.positive?
+
+    (BigDecimal(idr.to_s) / exchange_rate).ceil(2)
+  end
+
+  def self.amount(base:, code:)
+    number = Integer(code)
+    raise ArgumentError, "code must be between 1 and #{MAX_UNIQUE_CODE}" unless (1..MAX_UNIQUE_CODE).cover?(number)
+
+    BigDecimal(base.to_s) + number * CODE_UNIT
+  end
+
+  def self.available_codes(base:, reserved_amounts:)
+    baseline = BigDecimal(base.to_s)
+    reserved = reserved_amounts.each_with_object({}) do |value, codes|
+      code = (BigDecimal(value.to_s) - baseline) / CODE_UNIT
+      codes[code.to_i] = true if code.frac.zero? && (1..MAX_UNIQUE_CODE).cover?(code.to_i)
+    end
+    (1..MAX_UNIQUE_CODE).reject { |code| reserved.key?(code) }
+  end
+end
+
+require_relative "rails_crypto_payment/evm_rpc"
+require_relative "rails_crypto_payment/exchange_clients"

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: rails-crypto-payment
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Azmi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Framework-independent USDT amount reservation and deposit retrieval for
+  Rails payment integrations.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rails_crypto_payment.rb
+- lib/rails_crypto_payment/evm_rpc.rb
+- lib/rails_crypto_payment/exchange_clients.rb
+homepage: https://github.com/azmi2409/rails-crypto-payment
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Exact crypto amounts and exchange/chain deposit clients
+test_files: []