wallets 0.1.0

data/Rakefile

@@ -0,0 +1,30 @@
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "bundler/gem_tasks"
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "Wallets"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/generators/wallets/install_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module Wallets
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_migration_file
+        migration_template "create_wallets_tables.rb.erb", File.join(db_migrate_path, "create_wallets_tables.rb")
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/wallets.rb"
+      end
+
+      def display_post_install_message
+        say "\n🎉 The `wallets` gem has been installed.", :green
+        say "\nTo complete the setup:"
+        say "  1. Run 'rails db:migrate' to create the wallet tables."
+        say "     ⚠️  If you want a custom table prefix, set config.table_prefix in config/initializers/wallets.rb before migrating.", :yellow
+        say "  2. Add 'has_wallets' to any model that should own wallets."
+        say "  3. Adjust config/initializers/wallets.rb for your default asset, categories, and callbacks."
+        say "  4. Use owner.wallet(:asset_code) to start crediting, debiting, and transferring value."
+        say "\nYou now have an append-only wallet ledger with balances, allocations, and transfers.\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/generators/wallets/templates/create_wallets_tables.rb.erb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table wallets_table, id: primary_key_type do |t|
+      t.references :owner, polymorphic: true, null: false, type: foreign_key_type
+      t.string :asset_code, null: false
+      t.bigint :balance, null: false, default: 0
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
+
+      t.timestamps
+    end
+
+    add_index wallets_table, [:owner_type, :owner_id, :asset_code], unique: true, name: index_name("wallets_on_owner_and_asset_code")
+
+    create_table transfers_table, id: primary_key_type do |t|
+      t.references :from_wallet, null: false, type: foreign_key_type, foreign_key: { to_table: wallets_table }
+      t.references :to_wallet, null: false, type: foreign_key_type, foreign_key: { to_table: wallets_table }
+      t.string :asset_code, null: false
+      t.bigint :amount, null: false
+      t.string :category, null: false, default: "transfer"
+      t.string :expiration_policy, null: false, default: "preserve"
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
+
+      t.timestamps
+    end
+
+    create_table transactions_table, id: primary_key_type do |t|
+      t.references :wallet, null: false, type: foreign_key_type, foreign_key: { to_table: wallets_table }
+      t.bigint :amount, null: false
+      t.string :category, null: false
+      t.datetime :expires_at
+      t.references :transfer, type: foreign_key_type, foreign_key: { to_table: transfers_table }
+      t.send(json_column_type, :metadata, null: false, default: json_column_default)
+
+      t.timestamps
+    end
+
+    # Allocations are the basis for the bucket-based, FIFO inventory system.
+    create_table allocations_table, id: primary_key_type do |t|
+      # The negative spend transaction that is consuming value.
+      t.references :transaction, null: false, type: foreign_key_type,
+                                 foreign_key: { to_table: transactions_table },
+                                 index: { name: index_name("allocations_on_transaction_id") }
+
+      # The positive source transaction the value is being consumed from.
+      t.references :source_transaction, null: false, type: foreign_key_type,
+                                        foreign_key: { to_table: transactions_table },
+                                        index: { name: index_name("allocations_on_source_transaction_id") }
+
+      t.bigint :amount, null: false
+
+      t.timestamps
+    end
+
+    add_index transactions_table, :category
+    add_index transactions_table, :expires_at
+    add_index transactions_table, [:wallet_id, :amount], name: index_name("transactions_on_wallet_id_and_amount")
+    add_index transactions_table, [:expires_at, :id], name: index_name("transactions_on_expires_at_and_id")
+    add_index allocations_table, [:transaction_id, :source_transaction_id], name: index_name("allocations_on_tx_and_source_tx")
+    add_index transfers_table, [:from_wallet_id, :to_wallet_id, :asset_code], name: index_name("transfers_on_wallets_and_asset")
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    primary_key_type = setting || :primary_key
+    foreign_key_type = setting || :bigint
+    [primary_key_type, foreign_key_type]
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.downcase.include?("postgresql")
+
+    :json
+  end
+
+  # MySQL does not allow defaults on JSON columns, so models treat nil metadata
+  # the same as an empty hash when records are loaded.
+  def json_column_default
+    return nil if connection.adapter_name.downcase.include?("mysql")
+
+    {}
+  end
+
+  def table_prefix
+    Wallets.configuration.table_prefix
+  end
+
+  def wallets_table
+    "#{table_prefix}wallets"
+  end
+
+  def transactions_table
+    "#{table_prefix}transactions"
+  end
+
+  def allocations_table
+    "#{table_prefix}allocations"
+  end
+
+  def transfers_table
+    "#{table_prefix}transfers"
+  end
+
+  def index_name(suffix)
+    "index_#{table_prefix}#{suffix}"
+  end
+end

data/lib/generators/wallets/templates/initializer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+Wallets.configure do |config|
+  # The asset returned by owner.wallet with no argument.
+  # Common examples:
+  # - :credits for usage-based apps
+  # - :coins or :gems for games
+  # - :eur or :usd for marketplace balances
+  # - :wood for resource-based economies
+  config.default_asset = :credits
+
+  # Prefix for the generated tables.
+  #
+  # Set this BEFORE running rails db:migrate for the first time.
+  # Treat it as permanent once the wallet tables exist.
+  #
+  # config.table_prefix = "wallets_"
+
+  # Set to true only if your domain explicitly supports debt or overdrafts.
+  #
+  # config.allow_negative_balance = false
+
+  # Optional threshold that fires on_low_balance_reached when crossed.
+  # Set to nil to disable.
+  #
+  # config.low_balance_threshold = 100
+
+  # Extra business event labels so the ledger stays readable.
+  # These extend the built-in defaults:
+  # :credit, :debit, :transfer, :expiration, :adjustment
+  #
+  # config.additional_categories = %w[
+  #   ride_fare
+  #   seller_payout
+  #   reward_redemption
+  #   marketplace_sale
+  #   quest_reward
+  #   resource_gathered
+  # ]
+  #
+  #
+  # === Lifecycle Callbacks ===
+  #
+  # Hook into wallet events for analytics, notifications, and custom logic.
+  # All callbacks receive a context object with event-specific data.
+  #
+  # Available callbacks:
+  #   on_balance_credited      - After value is added to a wallet
+  #   on_balance_debited       - After value is deducted from a wallet
+  #   on_transfer_completed    - After a transfer between wallets succeeds
+  #   on_low_balance_reached   - When balance drops below the threshold
+  #   on_balance_depleted      - When balance reaches exactly zero
+  #   on_insufficient_balance  - When a debit or transfer is rejected
+  #
+  # Context object properties (available depending on event):
+  #   ctx.event            # Symbol - the event name
+  #   ctx.owner            # The wallet owner (User, Team, Guild, etc.)
+  #   ctx.wallet           # The Wallets::Wallet instance
+  #   ctx.amount           # Balance involved
+  #   ctx.previous_balance # Balance before the operation
+  #   ctx.new_balance      # Balance after the operation
+  #   ctx.transaction      # The Wallets::Transaction record
+  #   ctx.transfer         # The Wallets::Transfer record
+  #   ctx.category         # Transaction category
+  #   ctx.threshold        # Low balance threshold
+  #   ctx.metadata         # Additional event-specific context
+  #   ctx.to_h             # Hash representation without nil values
+  #
+  # IMPORTANT: Keep callbacks fast. Use background jobs for email,
+  # analytics, or anything that should not block balance operations.
+  #
+  # config.on_balance_credited do |ctx|
+  #   Rails.logger.info "[Wallets] Credited #{ctx.amount} to #{ctx.owner.class}##{ctx.owner.id}"
+  # end
+  #
+  # config.on_balance_debited do |ctx|
+  #   Rails.logger.info "[Wallets] Debited #{ctx.amount} from #{ctx.owner.class}##{ctx.owner.id}"
+  # end
+  #
+  # config.on_transfer_completed do |ctx|
+  #   Rails.logger.info "[Wallets] Transfer #{ctx.transfer.id} completed"
+  # end
+  #
+  # config.on_insufficient_balance do |ctx|
+  #   Rails.logger.info "[Wallets] #{ctx.owner.class}##{ctx.owner.id} needs #{ctx.amount}, has #{ctx.metadata[:available]}"
+  # end
+end

data/lib/wallets/callback_context.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Immutable event payload passed to lifecycle callbacks.
+  # Keeping callback data in one object makes it easier to extend callback APIs
+  # without breaking existing handlers.
+  CallbackContext = Struct.new(
+    :event,
+    :wallet,
+    :transfer,
+    :amount,
+    :previous_balance,
+    :new_balance,
+    :threshold,
+    :category,
+    :transaction,
+    :metadata,
+    keyword_init: true
+  ) do
+    def owner
+      wallet&.owner
+    end
+
+    def to_h
+      super.compact
+    end
+  end
+end

data/lib/wallets/callbacks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Centralized callback dispatcher with error isolation.
+  # Callback failures should never break the ledger write that triggered them.
+  module Callbacks
+    module_function
+
+    def dispatch(event, **context_data)
+      callback = Wallets.configuration.public_send(:"on_#{event}_callback")
+      return unless callback.is_a?(Proc)
+
+      context = CallbackContext.new(event: event, **context_data)
+      execute_safely(callback, context)
+    end
+
+    def execute_safely(callback, context)
+      case callback.arity
+      when 1, -1, -2
+        callback.call(context)
+      when 0
+        callback.call
+      else
+        log_warn "[Wallets] Callback has unexpected arity (#{callback.arity}). Expected 0 or 1."
+      end
+    rescue StandardError => e
+      log_error "[Wallets] Callback error for #{context.event}: #{e.class}: #{e.message}"
+      log_debug e.backtrace.join("\n")
+    end
+
+    def log_error(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      else
+        warn message
+      end
+    end
+
+    def log_warn(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn message
+      end
+    end
+
+    def log_debug(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
+        Rails.logger.debug(message)
+      end
+    end
+  end
+end

data/lib/wallets/configuration.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Configuration for the Wallets gem. This is the single source of truth for
+  # the wallet owner API, ledger callbacks, and installation-time table names.
+  class Configuration
+    # =========================================
+    # Basic Settings
+    # =========================================
+
+    attr_accessor :allow_negative_balance
+    attr_reader :default_asset, :additional_categories, :table_prefix
+    attr_reader :low_balance_threshold
+    attr_reader :transfer_expiration_policy
+
+    # =========================================
+    # Lifecycle Callbacks
+    # =========================================
+
+    attr_reader :on_balance_credited_callback,
+                :on_balance_debited_callback,
+                :on_transfer_completed_callback,
+                :on_low_balance_reached_callback,
+                :on_balance_depleted_callback,
+                :on_insufficient_balance_callback
+
+    def initialize
+      # Keep the out-of-the-box default close to the most common "main wallet"
+      # use case while still allowing apps to override it immediately.
+      @default_asset = :credits
+      @additional_categories = []
+      @allow_negative_balance = false
+      @low_balance_threshold = nil
+      @transfer_expiration_policy = :preserve
+      # This prefix is used by the models at runtime and by the install
+      # migration when it is executed for the first time.
+      @table_prefix = "wallets_"
+
+      @on_balance_credited_callback = nil
+      @on_balance_debited_callback = nil
+      @on_transfer_completed_callback = nil
+      @on_low_balance_reached_callback = nil
+      @on_balance_depleted_callback = nil
+      @on_insufficient_balance_callback = nil
+    end
+
+    def default_asset=(value)
+      value = normalize_asset_code(value)
+      raise ArgumentError, "Default asset can't be blank" if value.blank?
+
+      @default_asset = value.to_sym
+    end
+
+    def additional_categories=(categories)
+      raise ArgumentError, "Additional categories must be an array" unless categories.is_a?(Array)
+
+      @additional_categories = categories.map { |category| normalize_category(category) }.reject(&:blank?).uniq
+    end
+
+    def low_balance_threshold=(value)
+      if value
+        value = Integer(value)
+        raise ArgumentError, "Low balance threshold must be greater than or equal to zero" if value.negative?
+      end
+
+      @low_balance_threshold = value
+    end
+
+    def table_prefix=(value)
+      value = value.to_s
+      raise ArgumentError, "Table prefix can't be blank" if value.blank?
+
+      @table_prefix = value
+    end
+
+    def transfer_expiration_policy=(value)
+      normalized_value = value.to_s.strip.downcase.to_sym
+      allowed_values = %i[preserve none]
+
+      raise ArgumentError, "Transfer expiration policy must be one of: #{allowed_values.join(', ')}" unless allowed_values.include?(normalized_value)
+
+      @transfer_expiration_policy = normalized_value
+    end
+
+    def on_balance_credited(&block)
+      @on_balance_credited_callback = block
+    end
+
+    def on_balance_debited(&block)
+      @on_balance_debited_callback = block
+    end
+
+    def on_transfer_completed(&block)
+      @on_transfer_completed_callback = block
+    end
+
+    def on_low_balance_reached(&block)
+      @on_low_balance_reached_callback = block
+    end
+
+    def on_balance_depleted(&block)
+      @on_balance_depleted_callback = block
+    end
+
+    def on_insufficient_balance(&block)
+      @on_insufficient_balance_callback = block
+    end
+
+    private
+
+    def normalize_asset_code(value)
+      value.to_s.strip.downcase
+    end
+
+    def normalize_category(value)
+      value.to_s.strip
+    end
+  end
+end

data/lib/wallets/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Wallets
+  class Engine < ::Rails::Engine
+    isolate_namespace Wallets
+
+    # Load wallet models early so host apps can reference them during boot.
+    config.autoload_paths << File.expand_path("models", __dir__)
+    config.autoload_paths << File.expand_path("models/concerns", __dir__)
+
+    initializer "wallets.autoload", before: :set_autoload_paths do |app|
+      app.config.autoload_paths << root.join("lib")
+      app.config.autoload_paths << root.join("lib/wallets/models")
+      app.config.autoload_paths << root.join("lib/wallets/models/concerns")
+    end
+
+    initializer "wallets.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend Wallets::HasWallets::ClassMethods
+      end
+    end
+  end
+end

data/lib/wallets/models/allocation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Allocations link a negative spend transaction to the positive transactions it
+  # consumed from. This is what makes FIFO spending and expiration-aware balances
+  # possible without mutating historical transactions.
+  #
+  # This class supports embedding: subclasses can override config and table
+  # names without affecting the base Wallets::* behavior.
+  class Allocation < ApplicationRecord
+    class_attribute :embedded_table_name, default: nil
+    class_attribute :config_provider, default: -> { Wallets.configuration }
+
+    def self.table_name
+      embedded_table_name || "#{resolved_config.table_prefix}allocations"
+    end
+
+    def self.resolved_config
+      value = config_provider
+      value.respond_to?(:call) ? value.call : value
+    end
+
+    belongs_to :spend_transaction, class_name: "Wallets::Transaction", foreign_key: "transaction_id"
+    belongs_to :source_transaction, class_name: "Wallets::Transaction"
+
+    validates :amount, presence: true, numericality: { only_integer: true, greater_than: 0 }
+    validate :source_transaction_has_matching_asset
+    validate :allocation_does_not_exceed_remaining_amount
+
+    private
+
+    def source_transaction_has_matching_asset
+      return if spend_transaction.blank? || source_transaction.blank?
+      return if spend_transaction.wallet_id == source_transaction.wallet_id
+
+      errors.add(:source_transaction, "must belong to the same wallet as the spend transaction")
+    end
+
+    def allocation_does_not_exceed_remaining_amount
+      return if amount.blank? || source_transaction.blank?
+
+      if source_transaction.remaining_amount < amount
+        errors.add(:amount, "exceeds the remaining amount of the source transaction")
+      end
+    end
+  end
+end

data/lib/wallets/models/concerns/has_wallets.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Wallets
+  # Adds multi-wallet ownership to an Active Record model.
+  # One owner can have one wallet per asset code, with a default "main wallet"
+  # exposed via `owner.wallet` and `owner.main_wallet`.
+  module HasWallets
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def has_wallets(**options)
+        include Wallets::HasWallets unless included_modules.include?(Wallets::HasWallets)
+
+        @wallet_options = {
+          default_asset: Wallets.configuration.default_asset,
+          auto_create: true,
+          initial_balance: 0
+        }.merge(options)
+      end
+
+      def wallet_options
+        @wallet_options ||= {
+          default_asset: Wallets.configuration.default_asset,
+          auto_create: true,
+          initial_balance: 0
+        }
+      end
+    end
+
+    included do
+      has_many :wallets,
+               class_name: "Wallets::Wallet",
+               as: :owner,
+               dependent: :destroy
+
+      after_create :create_main_wallet, if: :should_auto_create_wallet?
+    end
+
+    def wallet_options
+      self.class.wallet_options
+    end
+
+    def wallet(asset_code = nil)
+      ensure_wallet(asset_code || wallet_options[:default_asset])
+    end
+
+    def wallet?(asset_code = nil)
+      find_wallet(asset_code || wallet_options[:default_asset]).present?
+    end
+
+    def main_wallet
+      wallet(wallet_options[:default_asset])
+    end
+
+    def find_wallet(asset_code = nil)
+      normalized_asset_code = normalize_asset_code(asset_code || wallet_options[:default_asset])
+      wallets.find_by(asset_code: normalized_asset_code)
+    end
+
+    private
+
+    def should_auto_create_wallet?
+      wallet_options[:auto_create] != false
+    end
+
+    def ensure_wallet(asset_code)
+      existing_wallet = find_wallet(asset_code)
+      return existing_wallet if existing_wallet.present?
+      return unless should_auto_create_wallet?
+      raise "Cannot create wallet for unsaved owner" unless persisted?
+
+      Wallet.create_for_owner!(
+        owner: self,
+        asset_code: asset_code,
+        initial_balance: initial_balance_for(asset_code)
+      )
+    end
+
+    def create_main_wallet
+      main_wallet
+    end
+
+    def normalize_asset_code(value)
+      value.to_s.strip.downcase
+    end
+
+    def initial_balance_for(asset_code)
+      return 0 unless normalize_asset_code(asset_code) == normalize_asset_code(wallet_options[:default_asset])
+
+      wallet_options[:initial_balance] || 0
+    end
+  end
+end