remitmd 0.1.0

data/lib/remitmd/models.rb

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+require "time"
+
+module Remitmd
+  # Supported chain IDs
+  module ChainId
+    BASE         = 8453
+    BASE_SEPOLIA = 84532
+  end
+
+  # ─── Status types ─────────────────────────────────────────────────────────
+
+  module EscrowStatus
+    PENDING   = "pending"
+    FUNDED    = "funded"
+    RELEASED  = "released"
+    CANCELLED = "cancelled"
+    EXPIRED   = "expired"
+  end
+
+  module TabStatus
+    OPEN    = "open"
+    CLOSED  = "closed"
+    SETTLED = "settled"
+  end
+
+  module StreamStatus
+    ACTIVE    = "active"
+    PAUSED    = "paused"
+    ENDED     = "ended"
+    CANCELLED = "cancelled"
+  end
+
+  module BountyStatus
+    OPEN      = "open"
+    AWARDED   = "awarded"
+    EXPIRED   = "expired"
+    RECLAIMED = "reclaimed"
+  end
+
+  module DepositStatus
+    LOCKED    = "locked"
+    RETURNED  = "returned"
+    FORFEITED = "forfeited"
+  end
+
+  # ─── Permit & Contract Addresses ─────────────────────────────────────────
+
+  # EIP-2612 permit signature for gasless USDC approval.
+  class PermitSignature
+    attr_reader :value, :deadline, :v, :r, :s
+
+    def initialize(value:, deadline:, v:, r:, s:)
+      @value    = value
+      @deadline = deadline
+      @v        = v
+      @r        = r
+      @s        = s
+    end
+
+    def to_h
+      { value: @value, deadline: @deadline, v: @v, r: @r, s: @s }
+    end
+  end
+
+  # ─── Value objects ────────────────────────────────────────────────────────
+
+  # Immutable model base. Builds from a hash with string or symbol keys.
+  class Model
+    def initialize(attrs)
+      attrs.each do |k, v|
+        instance_variable_set("@#{k}", v)
+        self.class.attr_reader(k.to_sym) unless respond_to?(k.to_sym)
+      end
+    end
+
+    def to_h
+      instance_variables.each_with_object({}) do |var, h|
+        h[var.to_s.delete("@").to_sym] = instance_variable_get(var)
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} #{to_h}>"
+    end
+
+    protected
+
+    def decimal(value)
+      return value if value.is_a?(BigDecimal)
+      return BigDecimal(value.to_s) if value
+      nil
+    end
+
+    def parse_time(value)
+      return value if value.is_a?(Time)
+      return Time.parse(value) if value.is_a?(String)
+      nil
+    end
+  end
+
+  # Contract addresses returned by GET /contracts.
+  class ContractAddresses < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @chain_id       = h["chain_id"]&.to_i
+      @usdc           = h["usdc"]
+      @router         = h["router"]
+      @escrow         = h["escrow"]
+      @tab            = h["tab"]
+      @stream         = h["stream"]
+      @bounty         = h["bounty"]
+      @deposit        = h["deposit"]
+      @fee_calculator = h["fee_calculator"]
+      @key_registry   = h["key_registry"]
+      @arbitration    = h["arbitration"]
+    end
+
+    attr_reader :chain_id, :usdc, :router, :escrow, :tab, :stream,
+                :bounty, :deposit, :fee_calculator, :key_registry, :arbitration
+  end
+
+  class Transaction < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id           = h["id"]
+      @tx_hash      = h["tx_hash"]
+      @from         = h["from"]
+      @to           = h["to"]
+      @amount       = decimal(h["amount"])
+      @fee          = decimal(h["fee"] || "0")
+      @memo         = h["memo"] || ""
+      @chain_id     = h["chain_id"]&.to_i
+      @block_number = h["block_number"]&.to_i || 0
+      @created_at   = parse_time(h["created_at"])
+    end
+
+    attr_reader :id, :tx_hash, :from, :to, :amount, :fee, :memo,
+                :chain_id, :block_number, :created_at
+
+    private :decimal, :parse_time
+  end
+
+  class Balance < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @usdc       = decimal(h["usdc"])
+      @address    = h["address"]
+      @chain_id   = h["chain_id"]&.to_i
+      @updated_at = parse_time(h["updated_at"])
+    end
+
+    attr_reader :usdc, :address, :chain_id, :updated_at
+
+    private :decimal, :parse_time
+  end
+
+  class Reputation < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @address           = h["address"]
+      @score             = h["score"]&.to_i || 0
+      @total_paid        = decimal(h["total_paid"])
+      @total_received    = decimal(h["total_received"])
+      @transaction_count = h["transaction_count"]&.to_i || 0
+      @member_since      = parse_time(h["member_since"])
+    end
+
+    attr_reader :address, :score, :total_paid, :total_received,
+                :transaction_count, :member_since
+
+    private :decimal, :parse_time
+  end
+
+  class Escrow < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id         = h["invoice_id"] || h["id"]
+      @payer      = h["payer"]
+      @payee      = h["payee"]
+      @amount     = decimal(h["amount"])
+      @fee        = decimal(h["fee"] || "0")
+      @status     = h["status"]
+      @memo       = h["memo"] || ""
+      @milestones = h["milestones"] || []
+      @splits     = h["splits"] || []
+      @expires_at = parse_time(h["expires_at"])
+      @created_at = parse_time(h["created_at"])
+    end
+
+    attr_reader :id, :payer, :payee, :amount, :fee, :status,
+                :memo, :milestones, :splits, :expires_at, :created_at
+
+    private :decimal, :parse_time
+  end
+
+  class Tab < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id          = h["id"]
+      @opener      = h["opener"] || h["payer"]
+      @provider    = h["provider"] || h["counterpart"]
+      @limit       = decimal(h["limit_amount"] || h["limit"])
+      @used        = decimal(h["used"] || "0")
+      @remaining   = decimal(h["remaining"] || h["limit_amount"] || h["limit"])
+      @status      = h["status"]
+      @created_at  = parse_time(h["created_at"])
+      @closes_at   = parse_time(h["closes_at"])
+    end
+
+    attr_reader :id, :opener, :provider, :limit, :used, :remaining,
+                :status, :created_at, :closes_at
+
+    # Backward compatibility alias
+    alias counterpart provider
+
+    private :decimal, :parse_time
+  end
+
+  class TabDebit < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @tab_id     = h["tab_id"]
+      @amount     = decimal(h["amount"])
+      @cumulative = decimal(h["cumulative"])
+      @call_count = h["call_count"]&.to_i || 0
+      @memo       = h["memo"] || ""
+      @sequence   = h["sequence"]&.to_i || 0
+      @signature  = h["signature"]
+    end
+
+    attr_reader :tab_id, :amount, :cumulative, :call_count, :memo, :sequence, :signature
+
+    private :decimal
+  end
+
+  class Stream < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id           = h["id"]
+      @sender       = h["sender"]
+      @recipient    = h["recipient"]
+      @rate_per_sec = decimal(h["rate_per_sec"])
+      @deposited    = decimal(h["deposited"])
+      @withdrawn    = decimal(h["withdrawn"] || "0")
+      @status       = h["status"]
+      @started_at   = parse_time(h["started_at"])
+      @ends_at      = parse_time(h["ends_at"])
+    end
+
+    attr_reader :id, :sender, :recipient, :rate_per_sec, :deposited,
+                :withdrawn, :status, :started_at, :ends_at
+
+    private :decimal, :parse_time
+  end
+
+  class Bounty < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id               = h["id"]
+      @poster           = h["poster"]
+      @amount           = decimal(h["amount"] || h["award"])
+      @task_description = h["task_description"] || h["description"]
+      @status           = h["status"]
+      @winner           = h["winner"] || ""
+      @expires_at       = parse_time(h["expires_at"])
+      @created_at       = parse_time(h["created_at"])
+    end
+
+    attr_reader :id, :poster, :amount, :task_description, :status,
+                :winner, :expires_at, :created_at
+
+    # Backward compatibility aliases
+    alias award amount
+    alias description task_description
+
+    private :decimal, :parse_time
+  end
+
+  class BountySubmission < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id          = h["id"]
+      @bounty_id   = h["bounty_id"]
+      @submitter   = h["submitter"]
+      @evidence_hash = h["evidence_hash"]
+      @status      = h["status"]
+      @created_at  = parse_time(h["created_at"])
+    end
+
+    attr_reader :id, :bounty_id, :submitter, :evidence_hash, :status, :created_at
+
+    private :parse_time
+  end
+
+  class Deposit < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id          = h["id"]
+      @depositor   = h["depositor"] || h["payer"]
+      @provider    = h["provider"] || h["beneficiary"]
+      @amount      = decimal(h["amount"])
+      @status      = h["status"]
+      @expires_at  = parse_time(h["expires_at"])
+      @created_at  = parse_time(h["created_at"])
+    end
+
+    attr_reader :id, :depositor, :provider, :amount,
+                :status, :expires_at, :created_at
+
+    # Backward compatibility alias
+    alias beneficiary provider
+
+    private :decimal, :parse_time
+  end
+
+  class Intent < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id         = h["id"]
+      @from       = h["from"]
+      @to         = h["to"]
+      @amount     = decimal(h["amount"])
+      @type       = h["type"]
+      @expires_at = parse_time(h["expires_at"])
+      @created_at = parse_time(h["created_at"])
+    end
+
+    attr_reader :id, :from, :to, :amount, :type, :expires_at, :created_at
+
+    private :decimal, :parse_time
+  end
+
+  class Budget < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @daily_limit       = decimal(h["daily_limit"])
+      @daily_used        = decimal(h["daily_used"])
+      @daily_remaining   = decimal(h["daily_remaining"])
+      @monthly_limit     = decimal(h["monthly_limit"])
+      @monthly_used      = decimal(h["monthly_used"])
+      @monthly_remaining = decimal(h["monthly_remaining"])
+      @per_tx_limit      = decimal(h["per_tx_limit"])
+    end
+
+    attr_reader :daily_limit, :daily_used, :daily_remaining,
+                :monthly_limit, :monthly_used, :monthly_remaining, :per_tx_limit
+
+    private :decimal
+  end
+
+  class SpendingSummary < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @address        = h["address"]
+      @period         = h["period"]
+      @total_spent    = decimal(h["total_spent"])
+      @total_fees     = decimal(h["total_fees"])
+      @tx_count       = h["tx_count"]&.to_i || 0
+      @top_recipients = h["top_recipients"] || []
+    end
+
+    attr_reader :address, :period, :total_spent, :total_fees,
+                :tx_count, :top_recipients
+
+    private :decimal
+  end
+
+  # One-time operator link for funding or withdrawing.
+  class LinkResponse < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @url            = h["url"]
+      @token          = h["token"]
+      @expires_at     = h["expires_at"]
+      @wallet_address = h["wallet_address"]
+    end
+
+    attr_reader :url, :token, :expires_at, :wallet_address
+  end
+
+  class Webhook < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      @id         = h["id"]
+      @wallet     = h["wallet"]
+      @url        = h["url"]
+      @events     = h["events"] || []
+      @chains     = h["chains"] || []
+      @active     = h["active"] == true
+      @created_at = parse_time(h["created_at"])
+      @updated_at = parse_time(h["updated_at"])
+    end
+
+    attr_reader :id, :wallet, :url, :events, :chains, :active, :created_at, :updated_at
+
+    private :parse_time
+  end
+
+  class TransactionList < Model
+    def initialize(attrs)
+      h = attrs.transform_keys(&:to_s)
+      items_raw = h["items"] || []
+      @items    = items_raw.map { |tx| Transaction.new(tx) }
+      @total    = h["total"]&.to_i || 0
+      @page     = h["page"]&.to_i || 1
+      @per_page = h["per_page"]&.to_i || 50
+      @has_more = h["has_more"] == true
+    end
+
+    attr_reader :items, :total, :page, :per_page, :has_more
+  end
+end

data/lib/remitmd/signer.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module Remitmd
+  # secp256k1 field prime p (constant — never changes)
+  SECP256K1_P = OpenSSL::BN.new(
+    "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F", 16
+  ).freeze
+
+  # Precomputed (p + 1) / 4 — the modular square root exponent for p ≡ 3 (mod 4).
+  # Avoids BN division at runtime (which returns Integer on some OpenSSL versions).
+  SECP256K1_SQRT_EXP = OpenSSL::BN.new(
+    "3FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFBFFFFF0C", 16
+  ).freeze
+
+  # Interface for signing remit.md API requests.
+  # Implement this module to provide custom signing (HSM, KMS, etc.).
+  module Signer
+    # Sign a 32-byte digest (raw binary). Returns 65-byte hex (r||s||v, Ethereum style).
+    def sign(digest)
+      raise NotImplementedError, "#{self.class}#sign is not implemented"
+    end
+
+    # The Ethereum address corresponding to the signing key (0x-prefixed).
+    def address
+      raise NotImplementedError, "#{self.class}#address is not implemented"
+    end
+  end
+
+  # Signs remit.md API requests using a raw secp256k1 private key.
+  # The private key is held in memory and never exposed via public methods.
+  class PrivateKeySigner
+    include Signer
+
+    def initialize(private_key_hex)
+      hex = private_key_hex.to_s.delete_prefix("0x")
+      raise ArgumentError, "Private key must be 64 hex characters" unless hex.match?(/\A[0-9a-fA-F]{64}\z/)
+
+      key_bytes = [hex].pack("H*")
+      group = OpenSSL::PKey::EC::Group.new("secp256k1")
+      bn = OpenSSL::BN.new(key_bytes, 2)
+      pub_point = group.generator.mul(bn)
+
+      # Build SEC1 DER-encoded private key (OpenSSL 3.x: PKey objects are immutable)
+      asn1 = OpenSSL::ASN1::Sequence.new([
+        OpenSSL::ASN1::Integer.new(1),
+        OpenSSL::ASN1::OctetString.new(key_bytes),
+        OpenSSL::ASN1::ASN1Data.new(
+          [OpenSSL::ASN1::ObjectId.new("secp256k1")], 0, :CONTEXT_SPECIFIC
+        ),
+        OpenSSL::ASN1::ASN1Data.new(
+          [OpenSSL::ASN1::BitString.new(pub_point.to_octet_string(:uncompressed))],
+          1, :CONTEXT_SPECIFIC
+        )
+      ])
+      @key = OpenSSL::PKey::EC.new(asn1.to_der)
+      @address = derive_address(pub_point)
+    end
+
+    # Sign a 32-byte EIP-712 digest (raw binary bytes).
+    # Returns a 0x-prefixed 65-byte hex signature (r || s || v) in Ethereum style.
+    # v is 27 (0x1b) or 28 (0x1c).
+    def sign(digest_bytes)
+      group = @key.group
+      n     = group.order
+
+      # ECDSA sign — dsa_sign_asn1 uses the input directly as the hash (no pre-hashing)
+      der  = @key.dsa_sign_asn1(digest_bytes)
+      asn1 = OpenSSL::ASN1.decode(der)
+      bn_r = asn1.value[0].value
+      bn_s = asn1.value[1].value
+
+      # Compute the recovery ID (0 or 1) by checking which candidate R recovers our address.
+      z     = OpenSSL::BN.new(digest_bytes.unpack1("H*"), 16)
+      r_inv = bn_r.mod_inverse(n)
+      # Q_candidate = r_inv * (s * R - z * G) = (r_inv*s)*R + (-(r_inv*z))*G
+      a = r_inv.mod_mul(bn_s, n)
+      b = n - r_inv.mod_mul(z, n)   # -r_inv*z mod n
+
+      # Normalize s to low-s canonical form (required by the server's k256 verifier).
+      # k256::ecdsa::Signature::from_slice rejects signatures with s > n/2.
+      half_n = n >> 1
+      if bn_s > half_n
+        bn_s = n - bn_s
+        # Recompute a and b for the new s
+        a = r_inv.mod_mul(bn_s, n)
+        b = n - r_inv.mod_mul(z, n)
+      end
+
+      v = nil
+      [0, 1].each do |parity|
+        r_point = recover_r_point(group, bn_r, parity)
+        next unless r_point
+
+        # Q = b*G + a*R (separate mul + add for OpenSSL 3.x compatibility)
+        bg = group.generator.mul(b)
+        ar = r_point.mul(a)
+        q = bg.add(ar)
+        candidate = derive_address(q)
+        if candidate.downcase == @address.downcase
+          v = 27 + parity
+          break
+        end
+      end
+      raise "Could not determine recovery ID — key or hash may be invalid" if v.nil?
+
+      # Build 65-byte Ethereum signature: r (32) || s (32) || v (1)
+      r_bytes = [bn_r.to_s(16).rjust(64, "0")].pack("H*")
+      s_bytes = [bn_s.to_s(16).rjust(64, "0")].pack("H*")
+      "0x#{(r_bytes + s_bytes + v.chr(Encoding::BINARY)).unpack1("H*")}"
+    end
+
+    # The Ethereum address (checksummed, 0x-prefixed).
+    attr_reader :address
+
+    # Never expose the key in inspect/to_s output.
+    def inspect
+      "#<Remitmd::PrivateKeySigner address=#{@address}>"
+    end
+
+    alias to_s inspect
+
+    private
+
+    # Recover the secp256k1 point R from r (big integer) and y-parity (0=even, 1=odd).
+    # Returns nil if the point is invalid.
+    def recover_r_point(group, bn_r, parity)
+      p = SECP256K1_P
+      x = bn_r
+      # y² = x³ + 7 (mod p)  — secp256k1 curve equation
+      x3  = x.mod_exp(OpenSSL::BN.new("3"), p)
+      rhs = x3 + OpenSSL::BN.new("7")
+      y_squared = rhs % p
+      # Tonelli–Shanks: since p ≡ 3 mod 4, sqrt = y²^((p+1)/4) mod p
+      y = y_squared.mod_exp(SECP256K1_SQRT_EXP, p)
+      # Verify that y² ≡ y_squared (mod p) — i.e., a square root exists
+      return nil unless y.mod_mul(y, p) == y_squared
+
+      y = p - y if (y.to_i & 1) != parity
+
+      hex_x = x.to_s(16).rjust(64, "0")
+      hex_y = y.to_s(16).rjust(64, "0")
+      OpenSSL::PKey::EC::Point.new(group, OpenSSL::BN.new("04#{hex_x}#{hex_y}", 16))
+    rescue OpenSSL::PKey::ECError
+      nil
+    end
+
+    def derive_address(public_key)
+      # Uncompressed public key: 04 || x (32) || y (32) — skip the 0x04 prefix
+      pub_bytes = [public_key.to_octet_string(:uncompressed).unpack1("H*")[2..]].pack("H*")
+      keccak    = keccak256_hex(pub_bytes)
+      "0x#{keccak[-40..]}"
+    end
+
+    # Returns the keccak256 digest as a hex string (no 0x prefix).
+    def keccak256_hex(data)
+      Remitmd::Keccak.hexdigest(data)
+    end
+  end
+end