mixin_bot 3.0.0 → 3.0.2

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

data/lib/mixin_bot/transfers.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Outbound transfer pipeline: a persisted transfer record enqueues a job
+  # that executes the Safe transaction pipeline exactly once per trace id,
+  # records the outcome on the record's state, and reconciles unknown
+  # outcomes (timeout after submission) against the snapshot API before any
+  # retry — the network's trace deduplication makes retries safe.
+  #
+  module Transfers
+    class << self
+      # Shared logger for the transfers integration; called with (level, detail).
+      attr_accessor :logger
+    end
+
+    self.logger = ->(level, detail) { warn "[mixin_transfers] #{level}: #{detail}" }
+  end
+end
+
+require_relative 'transfers/model'
+require_relative 'transfers/performer'
+require_relative 'transfers/reconcile'

data/lib/mixin_bot/version.rb

@@ -11,5 +11,5 @@ module MixinBot
   #
   # @see https://semver.org/
   #
-  VERSION = '3.0.0'
+  VERSION = '3.0.2'
 end

data/lib/mixin_bot.rb

@@ -32,6 +32,7 @@ require_relative 'mixin_bot/cli'
 require_relative 'mixin_bot/computer'
 require_relative 'mixin_bot/invoice'
 require_relative 'mixin_bot/monitor'
+require_relative 'mixin_bot/registry'
 require_relative 'mixin_bot/url_scheme'
 require_relative 'mixin_bot/utils'
 require_relative 'mixin_bot/nfo'
@@ -230,4 +231,6 @@ module MixinBot
       @deprecator ||= ActiveSupport::Deprecation.new('2.0', 'MixinBot')
     end
   end
+
+  extend Registry
 end

data/llms.txt

@@ -1,6 +1,6 @@
 # MixinBot
 
-> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 4.0. Gem version 3.0.0.
+> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 4.0. Gem version 3.0.2.
 
 Important notes:
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.2
 platform: ruby
 authors:
 - an-lee
@@ -300,6 +300,36 @@ files:
 - examples/blaze.rb
 - examples/blaze_async.rb
 - examples/config.yml.example
+- lib/generators/mixin_bot.rb
+- lib/generators/mixin_bot/authentication/USAGE
+- lib/generators/mixin_bot/authentication/authentication_generator.rb
+- lib/generators/mixin_bot/authentication/templates/app/controllers/concerns/authentication.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/controllers/sessions_controller.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/models/current.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/models/session.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/models/user.rb.tt
+- lib/generators/mixin_bot/authentication/templates/app/views/sessions/new.html.erb.tt
+- lib/generators/mixin_bot/authentication/templates/config/initializers/omniauth.rb.tt
+- lib/generators/mixin_bot/blaze/USAGE
+- lib/generators/mixin_bot/blaze/blaze_generator.rb
+- lib/generators/mixin_bot/blaze/templates/app/mixin/handlers/text_handler.rb
+- lib/generators/mixin_bot/blaze/templates/config/initializers/mixin_bot_blaze.rb
+- lib/generators/mixin_bot/install/USAGE
+- lib/generators/mixin_bot/install/install_generator.rb
+- lib/generators/mixin_bot/notifications/USAGE
+- lib/generators/mixin_bot/notifications/notifications_generator.rb
+- lib/generators/mixin_bot/notifications/templates/app/notifications/payment_received_notification.rb
+- lib/generators/mixin_bot/outputs/USAGE
+- lib/generators/mixin_bot/outputs/outputs_generator.rb
+- lib/generators/mixin_bot/outputs/templates/app/mixin/processors/deposit_processor.rb
+- lib/generators/mixin_bot/outputs/templates/app/models/mixin_output.rb
+- lib/generators/mixin_bot/outputs/templates/db/migrate/create_mixin_outputs.rb.tt
+- lib/generators/mixin_bot/transfers/USAGE
+- lib/generators/mixin_bot/transfers/templates/app/jobs/mixin_transfers/perform_job.rb
+- lib/generators/mixin_bot/transfers/templates/app/jobs/mixin_transfers/reconcile_job.rb
+- lib/generators/mixin_bot/transfers/templates/app/models/mixin_transfer.rb
+- lib/generators/mixin_bot/transfers/templates/db/migrate/create_mixin_transfers.rb.tt
+- lib/generators/mixin_bot/transfers/transfers_generator.rb
 - lib/mixin_bot.rb
 - lib/mixin_bot/address.rb
 - lib/mixin_bot/api.rb
@@ -347,6 +377,7 @@ files:
 - lib/mixin_bot/api/user.rb
 - lib/mixin_bot/api/withdraw.rb
 - lib/mixin_bot/blaze/reactor.rb
+- lib/mixin_bot/blaze/router.rb
 - lib/mixin_bot/bot_auth.rb
 - lib/mixin_bot/cache_store_adapter.rb
 - lib/mixin_bot/cli.rb
@@ -365,6 +396,7 @@ files:
 - lib/mixin_bot/configuration.rb
 - lib/mixin_bot/errors.rb
 - lib/mixin_bot/invoice.rb
+- lib/mixin_bot/json_decoder.rb
 - lib/mixin_bot/models.rb
 - lib/mixin_bot/models/address.rb
 - lib/mixin_bot/models/api_envelope.rb
@@ -376,11 +408,28 @@ files:
 - lib/mixin_bot/models/user.rb
 - lib/mixin_bot/monitor.rb
 - lib/mixin_bot/nfo.rb
+- lib/mixin_bot/notifications/mixin_channel.rb
+- lib/mixin_bot/outputs.rb
+- lib/mixin_bot/outputs/cursor_model.rb
+- lib/mixin_bot/outputs/envelope.rb
+- lib/mixin_bot/outputs/memory_stores.rb
+- lib/mixin_bot/outputs/poller.rb
+- lib/mixin_bot/outputs/processing_job.rb
+- lib/mixin_bot/outputs/processors.rb
+- lib/mixin_bot/outputs/receipt_model.rb
+- lib/mixin_bot/rails.rb
+- lib/mixin_bot/rails/railtie.rb
+- lib/mixin_bot/rails/tasks/poller.rake
+- lib/mixin_bot/registry.rb
 - lib/mixin_bot/session_store.rb
 - lib/mixin_bot/transaction.rb
 - lib/mixin_bot/transaction/buffer.rb
 - lib/mixin_bot/transaction/decoder.rb
 - lib/mixin_bot/transaction/encoder.rb
+- lib/mixin_bot/transfers.rb
+- lib/mixin_bot/transfers/model.rb
+- lib/mixin_bot/transfers/performer.rb
+- lib/mixin_bot/transfers/reconcile.rb
 - lib/mixin_bot/url_scheme.rb
 - lib/mixin_bot/utils.rb
 - lib/mixin_bot/utils/address.rb
@@ -423,7 +472,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A Ruby SDK for Mixin Network
 test_files: []