mixin_bot 2.6.0 → 3.0.2

data/lib/mixin_bot/outputs/processors.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Outputs
+    ##
+    # Base class for output processors. Subclass, implement class-level
+    # {matches?} and instance-level {#process}:
+    #
+    #   module Mixin
+    #     module Processors
+    #       class OrderDeposit < MixinBot::Outputs::Processor
+    #         def self.matches?(envelope)
+    #           !envelope.spent? && envelope.memo.to_s.start_with?('ORDER-')
+    #         end
+    #
+    #         def process
+    #           Order.settle_by_deposit!(envelope)
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # Processors live in app/mixin/processors (Rails autoloads them as
+    # Mixin::Processors::*). Every processor whose predicate matches an output
+    # gets a job enqueued — matches are independent side effects, and an
+    # output matching no processor is recorded only.
+    #
+    # Enqueue is at-least-once: processors should tolerate rare duplicate
+    # runs and can use the envelope's output_id as a natural idempotency key.
+    #
+    class Processor
+      def initialize(envelope)
+        @envelope = envelope
+      end
+
+      def call
+        process
+      end
+
+      attr_reader :envelope
+
+      # Override with the processor's selection predicate.
+      def self.matches?(_envelope)
+        false
+      end
+
+      def process
+        raise NotImplementedError, "#{self.class} must implement #process"
+      end
+    end
+
+    ##
+    # Processor discovery and selection over the Mixin::Processors namespace.
+    #
+    module Processors
+      NAMESPACE_NAME = 'Mixin::Processors'
+
+      module_function
+
+      ##
+      # All processor classes currently defined under Mixin::Processors. Under
+      # Rails the namespace is eager-loaded first so the poller process sees
+      # every processor without referencing each one.
+      #
+      # @return [Array<Class>]
+      #
+      def discover
+        eager_load_namespace! if defined?(::Rails.application) && ::Rails.application.respond_to?(:autoloaders)
+
+        namespace = namespace_class
+        return [] if namespace.nil?
+
+        namespace.constants.filter_map do |const|
+          candidate = namespace.const_get(const)
+          candidate if candidate.is_a?(Class) && candidate < Processor
+        end
+      end
+
+      # Finds a processor by fully-qualified class name (the payload the
+      # poller's jobs carry).
+      #
+      # @param name [String]
+      # @return [Class]
+      # @raise [NameError] when no such processor is loaded
+      #
+      def resolve(name)
+        constant = Object.const_get(name)
+        raise NameError, "#{name} is not a MixinBot::Outputs::Processor" unless constant.is_a?(Class) && constant < Processor
+
+        constant
+      end
+
+      ##
+      # Processors whose predicate matches the envelope.
+      #
+      # @return [Array<Class>]
+      #
+      def for_envelope(envelope, processors:)
+        processors.select { |processor| processor.matches?(envelope) }
+      end
+
+      def namespace_class
+        Object.const_get(NAMESPACE_NAME)
+      rescue NameError
+        nil
+      end
+
+      def eager_load_namespace!
+        autoloader = ::Rails.autoloaders.main
+        namespace = namespace_class
+        return if namespace.nil?
+
+        if autoloader.respond_to?(:eager_load_namespace)
+          autoloader.eager_load_namespace(namespace)
+        else
+          ::Rails.application.eager_load!
+        end
+      rescue Zeitwerk::SetupRequired, StandardError
+        # Best effort: an eager-load problem must not stop polling.
+        nil
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs/receipt_model.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module MixinBot
+  module Outputs
+    ##
+    # ActiveRecord concern for the generated +MixinOutput+ receipt model
+    # (mixin_bot:outputs generator). Implements the receipt-store interface
+    # the poller consumes, on top of the table's unique
+    # +(bot_app_id, output_id)+ index:
+    #
+    #   class MixinOutput < ApplicationRecord
+    #     include MixinBot::Outputs::ReceiptModel
+    #   end
+    #
+    # Including the model also registers it as the integration's receipt
+    # store (the mixin_bot:poller rake task) and as the processing job's
+    # receipt loader. The poller's resume cursor is derived from the receipts
+    # themselves — the newest output sequence per bot — so there is no
+    # separate cursor table.
+    #
+    # Required columns (see the generated migration): bot_app_id, output_id,
+    # amount, asset_id, state, transaction_hash, output_index, sequence
+    # (the outputs API's pagination key — the poller's cursor), memo,
+    # opponent_id, trace_id, snapshot_bridged, enqueued_at, plus Rails
+    # timestamps (created_at backs the sweep query).
+    #
+    module ReceiptModel
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Records the output or reports it as already seen. Uniqueness is
+        # enforced by the (bot_app_id, output_id) index, so concurrent pollers
+        # race safely.
+        def record!(bot_app_id:, output:)
+          existing = find_by(bot_app_id:, output_id: output['output_id'])
+          return [existing, :duplicate] if existing
+
+          receipt = create!(
+            bot_app_id:,
+            output_id: output['output_id'],
+            amount: output['amount'],
+            asset_id: output['asset_id'],
+            state: output['state'],
+            transaction_hash: output['transaction_hash'],
+            output_index: output['output_index'],
+            output_created_at: output['created_at']
+          )
+          [receipt, :created]
+        rescue ActiveRecord::RecordNotUnique
+          [find_by!(bot_app_id:, output_id: output['output_id']), :duplicate]
+        end
+
+        def mark_enqueued!(receipt)
+          receipt.update!(enqueued_at: Time.now)
+        end
+
+        # created_at is the Rails timestamp (when the receipt row was written),
+        # so the sweep's cutoff means "recorded before this moment".
+        def unenqueued(bot_app_id:, older_than:)
+          where(bot_app_id:, enqueued_at: nil).where(created_at: ...older_than)
+        end
+
+        # The poller's resume position: the newest output sequence recorded
+        # for this bot — unique and monotonic, and the key the outputs API
+        # paginates on (nil = fetch from the beginning). Derived from the
+        # receipts themselves — no separate cursor state.
+        def cursor_value(bot_app_id:)
+          where(bot_app_id:).maximum(:sequence)
+        end
+      end
+
+      # Caches the envelope's resolved snapshot data (one bridge attempt per
+      # output — including failures, which cache nils and the flag).
+      def cache_snapshot!(memo:, opponent_id:, trace_id:)
+        update!(memo:, opponent_id:, trace_id:, snapshot_bridged: true) unless frozen?
+      end
+
+      included do
+        MixinBot::Outputs.receipt_loader = method(:find)
+        MixinBot::Outputs.receipt_store = self
+      end
+    end
+  end
+end

data/lib/mixin_bot/outputs.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Output (transfer) polling integration: delivers every output touching the
+  # bot's Safe UTXO set — inbound or outbound — to application processor
+  # classes exactly once, via a standalone polling process and the
+  # application's job queue.
+  #
+  #   poller = MixinBot::Outputs::Poller.new(api: MixinBot.bot(:shop))
+  #   poller.run   # blocks; see the mixin_bot:poller rake task
+  #
+  module Outputs
+    class << self
+      # Shared logger for the outputs integration; called with (level, detail),
+      # same shape as MixinBot::Blaze::Reactor's logger. Injectable per
+      # component; this default is the fallback.
+      attr_accessor :logger
+
+      # Called with a receipt id to reload the receipt record when a processing
+      # job runs — set by the generated receipt model (ActiveRecord host apps).
+      # Without a loader, processing jobs raise a clear error explaining how to
+      # wire one.
+      attr_accessor :receipt_loader
+
+      # The receipt store the poller process uses — set by the generated
+      # receipt model when it loads. The mixin_bot:poller rake task refuses to
+      # run without one (polling with an in-memory store would silently lose
+      # dedup across restarts).
+      attr_accessor :receipt_store
+    end
+
+    self.logger = ->(level, detail) { warn "[mixin_outputs] #{level}: #{detail}" }
+  end
+end
+
+require_relative 'outputs/envelope'
+require_relative 'outputs/memory_stores'
+require_relative 'outputs/processors'
+require_relative 'outputs/poller'
+require_relative 'outputs/processing_job'
+require_relative 'outputs/receipt_model'

data/lib/mixin_bot/rails/railtie.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module MixinBot
+  # Registers the Rails integration's rake tasks and application-code
+  # conventions. Lives at lib/mixin_bot/rails/railtie.rb (loaded by
+  # `require 'mixin_bot/rails'`), named +MixinBot::Railtie+ — deliberately not
+  # +MixinBot::Rails+, which would lexically shadow ::Rails for code written
+  # inside module MixinBot.
+  #
+  # Application conventions:
+  # - +app/mixin/handlers+ hosts Blaze message handler classes
+  #   (+Mixin::Handlers::*+) and +app/mixin/processors+ hosts output
+  #   processor classes (+Mixin::Processors::*+). Rails' default path
+  #   inference would make +app/mixin+ itself a Zeitwerk root (mapping files
+  #   to +Handlers::*+ / +Processors::*+, not +Mixin::Handlers::*+), so the
+  #   railtie excludes it from the defaults and re-registers it with the
+  #   +Mixin+ namespace explicitly. Eager loading is the poller process's
+  #   responsibility (it eager-loads before discovering processors),
+  #   mirroring how Solid Queue's supervisor boots.
+  #
+  # Generator discovery needs no registration either: railties scans loaded
+  # gems for +lib/generators+ automatically.
+  class Railtie < ::Rails::Railtie
+    railtie_name 'mixin_bot'
+
+    initializer 'mixin_bot.exclude_default_mixin_root', before: :set_autoload_paths do |app|
+      app.config.paths.add 'app/mixin', autoload: false, eager_load: false
+    end
+
+    initializer 'mixin_bot.push_mixin_root', after: :set_autoload_paths, before: :setup_main_autoloader do |app|
+      mixin_root = app.root.join('app/mixin')
+      next unless mixin_root.directory?
+
+      Object.const_set(:Mixin, Module.new) unless Object.const_defined?(:Mixin)
+      app.autoloaders.main.push_dir(mixin_root, namespace: Mixin)
+    end
+
+    rake_tasks do
+      load File.expand_path('tasks/poller.rake', __dir__)
+    end
+  end
+end

data/lib/mixin_bot/rails/tasks/poller.rake

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+namespace :mixin_bot do
+  desc 'Poll Mixin outputs for the default bot (or the given [bot_name]) and enqueue processor jobs'
+  task :poller, [:bot] => :environment do |_task, args|
+    # Processor classes live in app/mixin/processors; eager load so discovery
+    # sees them (the poller process never references them directly).
+    Rails.application.eager_load!
+
+    unless MixinBot::Outputs.receipt_store
+      raise MixinBot::ArgumentError,
+            'no receipt store configured: run `rails g mixin_bot:outputs` (or include ' \
+            'MixinBot::Outputs::ReceiptModel in your receipt model) so polling dedup ' \
+            'survives restarts'
+    end
+
+    api = args[:bot] ? MixinBot.bot(args[:bot]) : MixinBot.api
+    poller = MixinBot::Outputs::Poller.new(
+      api:,
+      receipts: MixinBot::Outputs.receipt_store,
+      interval: Integer(ENV.fetch('MIXIN_BOT_POLL_INTERVAL', 5)),
+      asset: ENV.fetch('MIXIN_BOT_POLL_ASSET', nil),
+      members: ENV['MIXIN_BOT_POLL_MEMBERS']&.split(','),
+      threshold: ENV['MIXIN_BOT_POLL_THRESHOLD']&.then { |t| Integer(t) }
+    )
+
+    %w[TERM INT].each { |signal| trap(signal) { poller.stop } }
+
+    MixinBot::Outputs.logger.call(:info, "poller started (pid=#{Process.pid})")
+    poller.run
+    MixinBot::Outputs.logger.call(:info, 'poller stopped')
+  end
+end

data/lib/mixin_bot/rails.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Opt-in Rails integration layer: generators, railtie, and Rails glue.
+#
+# `require 'mixin_bot'` alone never loads any of this — the gem keeps no
+# runtime dependency on Rails. Host applications opt in explicitly:
+#
+#   # Gemfile
+#   gem 'mixin_bot'
+#   gem 'rails'
+#
+#   # config/application.rb (after the bundler groups)
+#   require 'mixin_bot/rails'
+#
+# The railtie registers the mixin_bot rake tasks (e.g. `mixin_bot:poller`).
+# Rails discovers the `lib/generators/mixin_bot/*` generators on its own.
+
+require 'mixin_bot'
+
+begin
+  require 'rails'
+rescue LoadError => e
+  raise LoadError,
+        'mixin_bot/rails requires the rails gem, which is not a runtime ' \
+        "dependency of mixin_bot. Add `gem 'rails'` to your Gemfile, or " \
+        "drop `require 'mixin_bot/rails'` if you only need the SDK. " \
+        "(#{e.message})"
+end
+
+require_relative 'blaze/router'
+require_relative 'outputs'
+require_relative 'transfers'
+require_relative 'rails/railtie'
+require_relative 'notifications/mixin_channel'

data/lib/mixin_bot/registry.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Named registry for running several bots (keystores) inside one process.
+  #
+  # The default bot stays on the global configuration (+MixinBot.configure+ /
+  # +MixinBot.api+). Additional bots register under a name and return a
+  # dedicated +MixinBot::API+ whose configuration is frozen after registration:
+  #
+  #   MixinBot.register_bot :shop,
+  #                        app_id: '...',
+  #                        session_id: '...',
+  #                        session_private_key: '...',
+  #                        server_public_key: '...'
+  #
+  #   MixinBot.bot(:shop).me
+  #
+  # Integration components built on top of the SDK (router, poller, transfers,
+  # notifications) accept the bot name and default to the global API client.
+  module Registry
+    ##
+    # Registers a bot under +name+ with {MixinBot::API#initialize} kwargs and
+    # freezes the resulting client's configuration.
+    #
+    # @param name [Symbol, String] registry key
+    # @param kwargs [Hash] bot credentials (see {Configuration#initialize});
+    #   empty kwargs would alias the global configuration and are rejected
+    # @return [MixinBot::API] the registered client
+    # @raise [MixinBot::ArgumentError] when the name is already registered or
+    #   no credentials are given
+    #
+    def register_bot(name, **kwargs)
+      raise MixinBot::ArgumentError, 'register_bot requires bot credentials' if kwargs.empty?
+      raise MixinBot::ArgumentError, "bot #{name.inspect} is already registered" if bots.key?(name.to_sym)
+
+      api = MixinBot::API.new(**kwargs)
+      api.config.freeze
+      bots[name.to_sym] = api
+    end
+
+    ##
+    # Returns the API client registered under +name+.
+    #
+    #   MixinBot.bot(:shop).assets
+    #
+    # @param name [Symbol, String] registry key
+    # @return [MixinBot::API]
+    # @raise [KeyError] when nothing is registered under that name
+    #
+    def bot(name)
+      bots.fetch(name.to_sym)
+    end
+
+    ##
+    # Finds a bot client by its app id: the default API when the app id is
+    # the global configuration's, else the registered bot carrying it.
+    #
+    # @param app_id [String, nil]
+    # @return [MixinBot::API, nil] nil when no bot carries that app id
+    #
+    def bot_by_app_id(app_id)
+      return nil if app_id.nil?
+      return api if config.app_id == app_id
+
+      bots.each_value.find { |client| client.config.app_id == app_id }
+    end
+
+    ##
+    # Returns the registry contents (bot name => API client). The hash is
+    # exposed for introspection; mutate it only between registrations.
+    #
+    # @return [Hash{Symbol => MixinBot::API}]
+    #
+    def bots
+      @bots ||= {}
+    end
+  end
+end

data/lib/mixin_bot/transfers/model.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module MixinBot
+  module Transfers
+    ##
+    # ActiveRecord concern for the generated +MixinTransfer+ model
+    # (mixin_bot:transfers generator): the transfer ledger's state machine and
+    # its execution entry points.
+    #
+    #   class MixinTransfer < ApplicationRecord
+    #     include MixinBot::Transfers::Model
+    #   end
+    #
+    #   transfer = MixinTransfer.create!(
+    #     recipient_id: user_id, asset_id: ASSET, amount: '1.5',
+    #     memo: 'payout', trace_id: SecureRandom.uuid
+    #   )
+    #   transfer.perform!                      # executes the Safe pipeline
+    #   transfer.reconcile!                    # resolves unknown outcomes
+    #   MixinTransfer.reconcile_pending!       # recurring-job entry point
+    #
+    # Required columns (see the generated migration): recipient_id, asset_id,
+    # amount, memo, trace_id (unique), state (default 'pending'),
+    # previous_state, transaction_hash, error, transitioned_at, bot_app_id
+    # (nil = the default bot), plus Rails timestamps.
+    #
+    module Model
+      extend ActiveSupport::Concern
+
+      STATES = %w[pending broadcast confirmed failed reconciling].freeze
+
+      # The allowed state graph: pending is pre-submission; broadcast means
+      # the transaction was submitted; confirmed and failed are terminal;
+      # reconciling means a submission outcome was indeterminate.
+      TRANSITIONS = {
+        'pending' => %w[broadcast failed reconciling],
+        'broadcast' => %w[confirmed reconciling],
+        'reconciling' => %w[broadcast confirmed failed],
+        'confirmed' => [].freeze,
+        'failed' => [].freeze
+      }.freeze
+
+      included do
+        validates :trace_id, presence: true, uniqueness: true
+        validates :recipient_id, :asset_id, :amount, presence: true
+        validates :state, inclusion: { in: STATES }
+      end
+
+      class_methods do
+        # Recurring-job entry point: resolve every transfer whose send attempt
+        # ended indeterminately (timeout after submission).
+        def reconcile_pending!
+          reconciling.find_each(&:reconcile!)
+        end
+      end
+
+      ##
+      # Audited state transition through the allowed graph. Never mutate
+      # #state directly. Same-state transitions are no-ops (idempotent
+      # retries); terminal states (confirmed, failed) never change.
+      #
+      # @param state [String] target state
+      # @param transaction_hash [String, nil] set when the network revealed it
+      # @param error [String, nil] set when the transition records a failure
+      # @raise [MixinBot::ArgumentError] when the transition is not allowed
+      #
+      def transition_to!(state, transaction_hash: nil, error: nil)
+        state = state.to_s
+        return self if state == self.state
+
+        unless TRANSITIONS.fetch(self.state, []).include?(state)
+          raise MixinBot::ArgumentError, "illegal transfer transition: #{self.state.inspect} → #{state.inspect}"
+        end
+
+        update!(
+          previous_state: self.state,
+          state:,
+          transaction_hash: transaction_hash || self.transaction_hash,
+          error:,
+          transitioned_at: Time.now
+        )
+      end
+
+      ##
+      # Executes the Safe pipeline for this transfer (idempotent per trace
+      # id). Definitive rejections mark the transfer failed; indeterminate
+      # network outcomes mark it reconciling. {Reconcile} resolves those.
+      #
+      def perform!
+        return self if state == 'confirmed'
+        raise MixinBot::ArgumentError, "transfer #{trace_id} is failed and will not be retried" if state == 'failed'
+
+        Performer.new(self, api: bot_api).perform
+      end
+
+      ##
+      # Resolves an indeterminate outcome: confirm from the trace's snapshot,
+      # or re-send with the same trace id (safe — the network deduplicates).
+      #
+      def reconcile!
+        Reconcile.new(self, api: bot_api).call
+      end
+
+      # The API client bound to this transfer's bot (bot_app_id or default).
+      def bot_api
+        MixinBot.bot_by_app_id(bot_app_id) || MixinBot.api
+      end
+    end
+  end
+end

data/lib/mixin_bot/transfers/performer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Transfers
+    ##
+    # Executes the Safe pipeline for one transfer record:
+    # build_utxos → build_safe_transaction → verify → sign → send, with the
+    # transfer's trace id as the request id, so network-side deduplication
+    # makes every retry safe.
+    #
+    # Outcome mapping:
+    # - success → broadcast (transaction hash stored), then confirmed when the
+    #   submission response carries the hash (it normally does);
+    # - definitive API rejection (insufficient funds, invalid request, ...) →
+    #   failed — never retried;
+    # - indeterminate network outcome (timeout/connection loss around the
+    #   submission) → reconciling — {Reconcile} resolves it.
+    #
+    class Performer
+      # Indeterminate-outcome network errors: the submission may or may not
+      # have landed, so the transfer goes to reconciling rather than failed.
+      NETWORK_ERRORS = [Faraday::Error, SocketError, Errno::ETIMEDOUT, Timeout::Error].freeze
+
+      attr_reader :transfer, :api
+
+      def initialize(transfer, api:)
+        @transfer = transfer
+        @api = api
+      end
+
+      ##
+      # Runs the pipeline and records the outcome. Re-raises unexpected
+      # (non-API, non-network) errors — those are bugs, left to the job
+      # backend's retry policy, with the transfer still in its prior state.
+      #
+      # @return [MixinBot::Transfers::Performer]
+      #
+      def perform
+        response = api.create_safe_transfer(
+          asset_id: transfer.asset_id,
+          amount: transfer.amount.to_d,
+          members: [transfer.recipient_id],
+          memo: transfer.memo.to_s,
+          trace_id: transfer.trace_id
+        )
+
+        data = response['data']
+        data = data.first if data.is_a?(Array)
+        data ||= {}
+
+        transfer.transition_to!('broadcast', transaction_hash: data['transaction_hash'])
+        transfer.transition_to!('confirmed', transaction_hash: data['transaction_hash']) if data['transaction_hash']
+        self
+      rescue MixinBot::APIError => e
+        transfer.transition_to!('failed', error: "#{e.class}: #{e.message}")
+        self
+      rescue Faraday::Error, SocketError, Errno::ETIMEDOUT, Timeout::Error => e
+        Transfers.logger.call(:indeterminate, "#{e.class}: #{e.message} (trace #{transfer.trace_id})")
+        transfer.transition_to!('reconciling', error: "#{e.class}: #{e.message}")
+        self
+      end
+    end
+  end
+end

data/lib/mixin_bot/transfers/reconcile.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module MixinBot
+  module Transfers
+    ##
+    # Resolves a transfer whose send attempt ended indeterminately (timeout
+    # or connection loss around the submission):
+    #
+    # - a snapshot exists for the trace id → the transfer landed; confirm
+    #   from the snapshot (no funds ever re-sent);
+    # - no snapshot exists → nothing landed; re-send with the same trace id —
+    #   the network's trace deduplication makes that safe.
+    #
+    class Reconcile
+      attr_reader :transfer, :api
+
+      def initialize(transfer, api:)
+        @transfer = transfer
+        @api = api
+      end
+
+      ##
+      # @return [Symbol] :confirmed (found in the network), :resent (nothing
+      #   existed; re-sent successfully) or :failed (the re-send was
+      #   definitively rejected)
+      #
+      def call
+        snapshot = fetch_snapshot_by_trace
+
+        if snapshot
+          transfer.transition_to!('confirmed',
+                                  transaction_hash: snapshot['transaction_hash'] || transfer.transaction_hash)
+          :confirmed
+        else
+          Performer.new(transfer, api:).perform
+          transfer.state == 'failed' ? :failed : :resent
+        end
+      end
+
+      private
+
+      # Returns the snapshot hash for the trace id, or nil when the network
+      # has none (the only outcome that justifies a re-send).
+      def fetch_snapshot_by_trace
+        response = api.safe_snapshot_by_trace(transfer.trace_id)
+        data = response['data']
+        data.is_a?(Hash) && data['snapshot_id'] ? data : nil
+      rescue MixinBot::NotFoundError
+        nil
+      end
+    end
+  end
+end