mixin_bot 1.4.0 → 2.0.0

data/lib/mixin_bot/configuration.rb

@@ -1,7 +1,47 @@
 # frozen_string_literal: true
 
 module MixinBot
+  ##
+  # Configuration class for storing Mixin bot credentials and settings.
+  #
+  # This class handles the configuration of bot credentials including:
+  # - Application ID and secret
+  # - Session ID and private key
+  # - Server public key
+  # - Spend key and PIN
+  # - API and Blaze host settings
+  #
+  # == Usage
+  #
+  # Configure globally:
+  #
+  #   MixinBot.configure do
+  #     app_id = 'your-app-id'
+  #     session_id = 'your-session-id'
+  #     session_private_key = 'your-private-key'
+  #     server_public_key = 'server-public-key'
+  #     spend_key = 'your-spend-key'
+  #   end
+  #
+  # Or create a specific configuration instance:
+  #
+  #   config = MixinBot::Configuration.new(
+  #     app_id: 'your-app-id',
+  #     session_id: 'your-session-id',
+  #     session_private_key: 'your-private-key',
+  #     server_public_key: 'server-public-key'
+  #   )
+  #
+  # == Key Conversion
+  #
+  # The configuration automatically handles key format conversions:
+  # - Ed25519 keys are converted from seed format (32 bytes) to full format (64 bytes)
+  # - Keys are converted to Curve25519 format when needed
+  # - Keys can be provided in various encodings (Base64, hex, etc.)
+  #
   class Configuration
+    ##
+    # List of configurable attributes.
     CONFIGURABLE_ATTRS = %i[
       app_id
       client_secret
@@ -18,6 +58,29 @@ module MixinBot
     ].freeze
     attr_accessor(*CONFIGURABLE_ATTRS)
 
+    ##
+    # Initializes a new Configuration instance.
+    #
+    # @param kwargs [Hash] configuration options
+    # @option kwargs [String] :app_id the application ID (or :client_id)
+    # @option kwargs [String] :client_secret the client secret
+    # @option kwargs [String] :session_id the session ID
+    # @option kwargs [String] :session_private_key the session private key (or :private_key)
+    # @option kwargs [String] :server_public_key the server public key (or :pin_token)
+    # @option kwargs [String] :spend_key the spend private key
+    # @option kwargs [String] :pin the PIN (defaults to spend_key if not provided)
+    # @option kwargs [String] :api_host ('api.mixin.one') the API host
+    # @option kwargs [String] :blaze_host ('blaze.mixin.one') the Blaze WebSocket host
+    # @option kwargs [Boolean] :debug (false) enable debug logging
+    #
+    # @example
+    #   config = MixinBot::Configuration.new(
+    #     app_id: '25696f85-b7b4-4509-8c3f-2684a8fc4a2a',
+    #     session_id: '25696f85-b7b4-4509-8c3f-2684a8fc4a2a',
+    #     session_private_key: 'base64_encoded_key',
+    #     server_public_key: 'base64_encoded_key'
+    #   )
+    #
     def initialize(**kwargs)
       @app_id = kwargs[:app_id] || kwargs[:client_id]
       @client_secret = kwargs[:client_secret]
@@ -32,12 +95,32 @@ module MixinBot
       self.pin = kwargs[:pin] || spend_key
     end
 
+    ##
+    # Validates if the configuration has all required credentials.
+    #
+    # Required fields are:
+    # - app_id
+    # - session_id
+    # - session_private_key
+    # - server_public_key
+    #
+    # @return [Boolean] true if all required fields are present
+    #
     def valid?
       %i[app_id session_id session_private_key server_public_key].all? do |attr|
         send(attr).present?
       end
     end
 
+    ##
+    # Sets the session private key with automatic format conversion.
+    #
+    # Handles Ed25519 key conversion:
+    # - If key is 32 bytes (seed), converts to 64-byte keypair
+    # - Automatically converts to Curve25519 format for encryption
+    #
+    # @param key [String] the session private key in various formats
+    #
     def session_private_key=(key)
       return if key.blank?
 
@@ -52,19 +135,35 @@ module MixinBot
       @session_private_key_curve25519 = JOSE::JWA::Ed25519.sk_to_curve25519(@session_private_key) if @session_private_key.size == 64
     end
 
+    ##
+    # Sets the server public key with automatic format conversion.
+    #
+    # Converts Ed25519 public key to Curve25519 format when needed.
+    # Handles both hex-encoded and Base64-encoded keys.
+    #
+    # @param key [String] the server public key
+    #
     def server_public_key=(key)
       return if key.blank?
 
       @server_public_key = decode_key key
       # HEX encoded
       @server_public_key_curve25519 =
-        if key.match?(/\A[\h]{32,}\z/i)
+        if key.match?(/\A\h{32,}\z/i)
           JOSE::JWA::Ed25519.pk_to_curve25519 @server_public_key
         else
           server_public_key
         end
     end
 
+    ##
+    # Sets the spend key with automatic format conversion.
+    #
+    # Used for signing transactions in the Safe API.
+    # Converts from seed format to full keypair if needed.
+    #
+    # @param key [String] the spend private key
+    #
     def spend_key=(key)
       return if key.blank?
 
@@ -77,6 +176,14 @@ module MixinBot
         end
     end
 
+    ##
+    # Sets the PIN with automatic format conversion.
+    #
+    # The PIN is used for certain operations requiring additional authorization.
+    # Defaults to the spend_key if not explicitly set.
+    #
+    # @param key [String] the PIN key
+    #
     def pin=(key)
       return if key.blank?
 

data/lib/mixin_bot/errors.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Base error class for all MixinBot errors.
+  #
+  class Error < StandardError; end
+
+  ##
+  # Raised when invalid arguments are provided.
+  #
+  class ArgumentError < StandardError; end
+
+  ##
+  # Raised when HTTP request fails.
+  #
+  class HttpError < Error; end
+
+  ##
+  # Raised when a request to Mixin API fails.
+  #
+  class RequestError < Error; end
+
+  ##
+  # Raised when Mixin API returns an error response.
+  #
+  class ResponseError < Error; end
+
+  ##
+  # Raised when a requested resource is not found (HTTP 404).
+  #
+  class NotFoundError < Error; end
+
+  ##
+  # Raised when a user is not found (error code 10404).
+  #
+  class UserNotFoundError < Error; end
+
+  ##
+  # Raised when authentication fails (HTTP 401).
+  #
+  class UnauthorizedError < Error; end
+
+  ##
+  # Raised when access is forbidden (HTTP 403).
+  #
+  class ForbiddenError < Error; end
+
+  ##
+  # Raised when there is insufficient balance for a transaction (error code 20117).
+  #
+  class InsufficientBalanceError < Error; end
+
+  ##
+  # Raised when selected UTXOs cannot cover the requested amount (mirrors Go +UtxoInsufficientError+).
+  #
+  class UtxoInsufficientError < InsufficientBalanceError
+    attr_reader :total_input, :total_output, :output_size
+
+    def initialize(message, total_input: nil, total_output: nil, output_size: nil)
+      super(message)
+      @total_input = total_input
+      @total_output = total_output
+      @output_size = output_size
+    end
+  end
+
+  ##
+  # Raised when there is insufficient pool for a transaction (error code 30103).
+  #
+  class InsufficientPoolError < Error; end
+
+  ##
+  # Raised when PIN verification fails (error codes 20118, 20119).
+  #
+  class PinError < Error; end
+
+  ##
+  # Raised when NFO memo format is invalid.
+  #
+  class InvalidNfoFormatError < Error; end
+
+  ##
+  # Raised when UUID format is invalid.
+  #
+  class InvalidUuidFormatError < Error; end
+
+  ##
+  # Raised when transaction format is invalid.
+  #
+  class InvalidTransactionFormatError < Error; end
+
+  ##
+  # Raised when configuration is not valid or incomplete.
+  #
+  class ConfigurationNotValidError < Error; end
+
+  ##
+  # Raised when invoice format is invalid.
+  #
+  class InvalidInvoiceFormatError < Error; end
+end

data/lib/mixin_bot/models/address.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Withdrawal address record (+/addresses+).
+    #
+    class Address < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models/api_envelope.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Wraps a raw Mixin API JSON object so callers can use both:
+    # - +response['data']['user_id']+ (envelope shape)
+    # - +response['user_id']+ (flattened shape, matching legacy +merge!+ behaviour)
+    #
+    class ApiEnvelope < SimpleDelegator
+      def [](key)
+        k = key.is_a?(Symbol) ? key.to_s : key
+        inner = __getobj__
+        return inner[k] if inner.key?(k)
+
+        data = inner['data']
+        return data[k] if data.is_a?(Hash) && data.key?(k)
+
+        nil
+      end
+
+      def dig(*keys)
+        return nil if keys.empty?
+
+        k0 = keys[0]
+        k0 = k0.to_s if k0.is_a?(Symbol)
+        inner = __getobj__
+
+        if inner.key?(k0)
+          v = inner[k0]
+          return v if keys.size == 1
+
+          return v.dig(*keys[1..]) if v.respond_to?(:dig)
+        end
+
+        data = inner['data']
+        return nil unless data.is_a?(Hash) && data.key?(k0)
+
+        v = data[k0]
+        return v if keys.size == 1
+
+        v.respond_to?(:dig) ? v.dig(*keys[1..]) : nil
+      end
+
+      def key?(key)
+        k = key.is_a?(Symbol) ? key.to_s : key
+        inner = __getobj__
+        inner.key?(k) || (inner['data'].is_a?(Hash) && inner['data'].key?(k))
+      end
+
+      alias include? key?
+      alias has_key? key?
+
+      def with_indifferent_access
+        inner = __getobj__
+        base = inner.dup
+        d = base['data']
+        merged = d.is_a?(Hash) ? base.merge(d) : base
+        merged.with_indifferent_access
+      end
+
+      def to_h
+        __getobj__
+      end
+    end
+  end
+end

data/lib/mixin_bot/models/asset.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Wallet asset row (+/assets+, +/assets/:id+).
+    #
+    class Asset < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models/ghost_keys.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Ghost key material returned by +/safe/keys+.
+    #
+    class GhostKeys < ApiEnvelope
+    end
+
+    class GhostKeyRequest < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models/output.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Safe API UTXO / output row (+/safe/outputs+).
+    #
+    class Output < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models/safe_multisig_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Safe multisig request (+/safe/multisigs+).
+    #
+    class SafeMultisigRequest < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models/sequencer_transaction_request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Sequencer transaction request (+/safe/transaction/requests+, +/safe/transactions+).
+    #
+    class SequencerTransactionRequest < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models/user.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Models
+    ##
+    # Typed view of a Mixin +User+ payload (+/me+, +/users/:id+, etc.).
+    #
+    class User < ApiEnvelope
+    end
+  end
+end

data/lib/mixin_bot/models.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'models/api_envelope'
+require_relative 'models/user'
+require_relative 'models/output'
+require_relative 'models/ghost_keys'
+require_relative 'models/sequencer_transaction_request'
+require_relative 'models/safe_multisig_request'
+require_relative 'models/address'
+require_relative 'models/asset'

data/lib/mixin_bot/monitor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module MixinBot
+  # Monitoring helpers (parity with Go monitor package).
+  module Monitor
+    class AppMessage
+      attr_accessor :project, :status, :data
+
+      def initialize(project: nil, status: 0, data: [])
+        @project = project
+        @status = status
+        @data = data
+      end
+
+      def self.load(yaml_str)
+        h = YAML.safe_load(yaml_str, permitted_classes: [Symbol], aliases: true)
+        new(
+          project: h['project'],
+          status: h['status'] || 0,
+          data: Array(h['data'])
+        )
+      end
+
+      def marshal
+        YAML.dump(
+          'project' => project,
+          'status' => status,
+          'data' => data
+        )
+      end
+    end
+
+    class << self
+      def unmarshal_app_message(bytes)
+        AppMessage.load(bytes)
+      end
+
+      def report_to_monitor(api, asset:, amount:, receivers:, threshold:, message:, trace: nil, **transfer_opts)
+        memo = message.is_a?(AppMessage) ? message.marshal : message.to_s
+        mix = MixinBot::MixAddress.from_members(members: receivers, threshold:)
+        trace ||= MixinBot.utils.unique_object_id(mix.address, asset, amount, api.config.app_id, memo,
+                                                  (Time.now.to_i / 60).to_s)
+        existing = begin
+          api.safe_transaction(trace)
+        rescue StandardError
+          nil
+        end
+        return existing if existing.present? && existing['data'].present?
+
+        api.create_safe_transfer(
+          members: receivers,
+          threshold:,
+          asset_id: asset,
+          amount:,
+          trace_id: trace,
+          memo:,
+          **transfer_opts
+        )
+      end
+
+      def check_retryable_error(error)
+        return false if error.nil?
+
+        reason = error.message.to_s.downcase
+        return true if reason.include?('timeout')
+        return true if reason.include?('internal server')
+        return true if reason.include?('insufficient')
+        return true if reason.include?('inputs locked by')
+        return true if reason.include?('by other transaction')
+
+        false
+      end
+    end
+  end
+end

data/lib/mixin_bot/transaction/buffer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MixinBot
+  class Transaction
+    ##
+    # Byte cursor for decoding raw transaction bytes.
+    #
+    class Buffer
+      attr_reader :bytes
+
+      def initialize(bytes)
+        @bytes = bytes
+      end
+
+      def shift(byte_count = nil)
+        return @bytes.shift if byte_count.nil?
+
+        @bytes.shift(byte_count)
+      end
+
+      def peek(byte_count)
+        @bytes[0, byte_count]
+      end
+
+      def size
+        @bytes.size
+      end
+
+      def empty?
+        @bytes.empty?
+      end
+    end
+  end
+end