token_ledger 0.1.0

data/lib/generators/token_ledger/install/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module TokenLedger
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      class_option :owner_model, type: :string, default: "User",
+        desc: "The model that owns tokens (e.g., User, Team)"
+
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_ledger_migration
+        migration_template "create_ledger_tables.rb",
+          "db/migrate/create_ledger_tables.rb"
+      end
+
+      def copy_owner_migration
+        @owner_class_name = options[:owner_model]
+        @owner_table_name = @owner_class_name.tableize
+
+        migration_template "add_cached_balance_to_owner.rb",
+          "db/migrate/add_cached_balance_to_#{@owner_table_name}.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def owner_class_name
+        @owner_class_name
+      end
+
+      def owner_table_name
+        @owner_table_name
+      end
+    end
+  end
+end

data/lib/generators/token_ledger/install/templates/README

@@ -0,0 +1,41 @@
+===============================================================================
+
+  TokenLedger has been installed!
+
+  Created migrations:
+    ✓ db/migrate/XXXXXX_create_ledger_tables.rb
+    ✓ db/migrate/XXXXXX_add_cached_balance_to_users.rb
+
+===============================================================================
+
+Next steps:
+
+  1. Run migrations:
+     rails db:migrate
+
+  2. Add to app/models/user.rb:
+
+     has_many :ledger_transactions,
+              as: :owner,
+              class_name: "TokenLedger::LedgerTransaction"
+
+     def balance
+       cached_balance
+     end
+
+  3. Optional: Create seed accounts (see README for examples)
+
+  4. Start using the ledger:
+
+     TokenLedger::Manager.deposit(
+       owner: user,
+       amount: 100,
+       description: "Welcome bonus",
+       external_source: "promo",
+       external_id: "signup_#{user.id}"
+     )
+
+  5. Read the full documentation:
+     https://github.com/wuliwong/token_ledger#readme
+
+===============================================================================

data/lib/generators/token_ledger/install/templates/add_cached_balance_to_owner.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddCachedBalanceTo<%= owner_class_name.pluralize %> < ActiveRecord::Migration[7.0]
+  def change
+    add_column :<%= owner_table_name %>, :cached_balance, :bigint, default: 0, null: false
+    add_index :<%= owner_table_name %>, :cached_balance
+  end
+end

data/lib/generators/token_ledger/install/templates/create_ledger_tables.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+class CreateLedgerTables < ActiveRecord::Migration[7.0]
+  def change
+    create_table :ledger_accounts do |t|
+      t.string :code, null: false
+      t.string :name, null: false
+      t.bigint :current_balance, default: 0, null: false
+      t.jsonb :metadata, default: {}, null: false
+      t.timestamps
+
+      t.index :code, unique: true
+      t.index :current_balance
+    end
+
+    create_table :ledger_transactions do |t|
+      t.string :transaction_type, null: false
+      t.string :description
+      t.references :owner, polymorphic: true
+      t.bigint :parent_transaction_id
+      t.string :external_source
+      t.string :external_id
+      t.jsonb :metadata, default: {}, null: false
+      t.timestamps
+
+      t.index [:external_source, :external_id], unique: true, where: "external_source IS NOT NULL"
+      t.index [:owner_type, :owner_id, :created_at]
+      t.index [:transaction_type, :created_at]
+      t.index :parent_transaction_id
+    end
+
+    # Add foreign key constraint for parent-child transaction relationships
+    add_foreign_key :ledger_transactions, :ledger_transactions,
+                    column: :parent_transaction_id,
+                    on_delete: :restrict
+
+    create_table :ledger_entries do |t|
+      t.references :account, null: false, foreign_key: { to_table: :ledger_accounts, on_delete: :restrict }
+      t.references :transaction, null: false, foreign_key: { to_table: :ledger_transactions, on_delete: :restrict }
+      t.string :entry_type, null: false
+      t.bigint :amount, null: false
+      t.jsonb :metadata, default: {}, null: false
+      t.timestamps
+
+      t.index [:account_id, :created_at]
+      t.index [:transaction_id, :entry_type]
+    end
+
+    # Add CHECK constraints for data integrity
+    add_check_constraint :ledger_entries, "amount > 0", name: "positive_amount"
+    add_check_constraint :ledger_entries, "entry_type IN ('debit', 'credit')", name: "valid_entry_type"
+    add_check_constraint :ledger_transactions,
+      "transaction_type IN ('deposit', 'spend', 'reserve', 'capture', 'release', 'adjustment')",
+      name: "valid_transaction_type"
+    add_check_constraint :ledger_transactions,
+      "(external_source IS NULL AND external_id IS NULL) OR (external_source IS NOT NULL AND external_id IS NOT NULL)",
+      name: "external_source_id_consistency"
+  end
+end

data/lib/token_ledger/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  class Error < StandardError; end
+  class InsufficientFundsError < Error; end
+  class ImbalancedTransactionError < Error; end
+  class DuplicateTransactionError < Error; end
+  class AccountNotFoundError < Error; end
+end

data/lib/token_ledger/models/ledger_account.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  class LedgerAccount < ActiveRecord::Base
+    self.table_name = "ledger_accounts"
+
+    has_many :ledger_entries, class_name: "TokenLedger::LedgerEntry", foreign_key: "account_id", dependent: :restrict_with_error
+
+    validates :code, presence: true, uniqueness: true
+    validates :name, presence: true
+    validates :current_balance, presence: true, numericality: { only_integer: true }
+
+    def self.find_or_create_account(code:, name:)
+      find_or_create_by!(code: code) do |account|
+        account.name = name
+        account.current_balance = 0
+        account.metadata = {}
+      end
+    end
+  end
+end

data/lib/token_ledger/models/ledger_entry.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  class LedgerEntry < ActiveRecord::Base
+    self.table_name = "ledger_entries"
+
+    belongs_to :account, class_name: "TokenLedger::LedgerAccount", required: true
+    belongs_to :ledger_transaction, class_name: "TokenLedger::LedgerTransaction", foreign_key: "transaction_id", required: true
+
+    validates :entry_type, presence: true, inclusion: { in: %w[debit credit] }
+    validates :amount, presence: true, numericality: { greater_than: 0, only_integer: true }
+  end
+end

data/lib/token_ledger/models/ledger_transaction.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  class LedgerTransaction < ActiveRecord::Base
+    self.table_name = "ledger_transactions"
+
+    belongs_to :owner, polymorphic: true, optional: true
+    belongs_to :parent_transaction, class_name: "TokenLedger::LedgerTransaction", optional: true
+    has_many :child_transactions, class_name: "TokenLedger::LedgerTransaction", foreign_key: "parent_transaction_id", dependent: :nullify
+    has_many :ledger_entries, class_name: "TokenLedger::LedgerEntry", foreign_key: "transaction_id", dependent: :destroy
+
+    validates :transaction_type, presence: true
+    validates :description, presence: true
+    validates :external_id, uniqueness: { scope: :external_source }, if: -> { external_source.present? }
+
+    def amount
+      ledger_entries.where(entry_type: "debit").sum(:amount)
+    end
+  end
+end

data/lib/token_ledger/services/account.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  class Account
+    def self.find_or_create(code:, name:)
+      LedgerAccount.find_or_create_account(code: code, name: name)
+    end
+  end
+end

data/lib/token_ledger/services/balance.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  class Balance
+    # Calculate balance from entries (source of truth)
+    def self.calculate(account_or_code)
+      account = account_or_code.is_a?(String) ?
+        LedgerAccount.find_by(code: account_or_code) :
+        account_or_code
+      return 0 unless account
+
+      entries = LedgerEntry.where(account: account)
+
+      entries.sum do |entry|
+        case entry.entry_type
+        when "debit" then entry.amount
+        when "credit" then -entry.amount
+        else 0
+        end
+      end
+    end
+
+    # Reconcile cached balance with calculated balance
+    def self.reconcile!(account_or_code)
+      account = account_or_code.is_a?(String) ?
+        LedgerAccount.find_by(code: account_or_code) :
+        account_or_code
+      return unless account
+
+      calculated = calculate(account)
+      cached = account.current_balance
+
+      if calculated != cached
+        account.update_column(:current_balance, calculated)
+      end
+
+      calculated
+    end
+
+    # Reconcile user's cached balance
+    def self.reconcile_user!(user)
+      wallet_account = LedgerAccount.find_by(code: "wallet:#{user.id}")
+      raise AccountNotFoundError, "Account not found for User ##{user.id}" unless wallet_account
+
+      reconcile!(wallet_account)
+      user.update_column(:cached_balance, wallet_account.current_balance)
+    end
+  end
+end

data/lib/token_ledger/services/manager.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module TokenLedger
+  class Manager
+    # Deposit tokens (purchase, bonus)
+    def self.deposit(owner:, amount:, description:, external_source: nil, external_id: nil, metadata: {})
+      logger.info "TokenLedger::Manager.deposit called - Owner: #{owner&.class&.name}##{owner&.id}, Amount: #{amount}, Source: #{external_source}, ID: #{external_id}"
+
+      return if amount.zero?
+
+      # Determine token source account
+      source_code = external_source ? "source:#{external_source}" : "source:other"
+      source_name = external_source ? "#{external_source.capitalize} Token Source" : "Other Token Source"
+
+      logger.info "Calling record_transaction for deposit"
+      record_transaction(
+        type: "deposit",
+        description: description,
+        owner: owner,
+        external_source: external_source,
+        external_id: external_id,
+        metadata: metadata,
+        entries: [
+          {
+            account_code: "wallet:#{owner.id}",
+            account_name: "User #{owner.id} Wallet",
+            type: :debit,
+            amount: amount
+          },
+          {
+            account_code: source_code,
+            account_name: source_name,
+            type: :credit,
+            amount: amount
+          }
+        ]
+      )
+    end
+
+    # Simple spend method - deducts tokens immediately
+    # DO NOT use this with external API calls - use reserve/capture/release instead
+    def self.spend(owner:, amount:, description:, metadata: {})
+      return if amount.zero?
+
+      record_transaction(
+        type: "spend",
+        description: description,
+        owner: owner,
+        metadata: metadata,
+        entries: [
+          {
+            account_code: "wallet:#{owner.id}",
+            account_name: "User #{owner.id} Wallet",
+            type: :credit,
+            amount: amount,
+            enforce_positive: true # No overdraft
+          },
+          {
+            account_code: "sink:consumed",
+            account_name: "Tokens Consumed",
+            type: :debit,
+            amount: amount
+          }
+        ]
+      )
+    end
+
+    # Reserve/Capture/Release pattern for spending with external APIs
+    def self.spend_with_api(owner:, amount:, description:, metadata: {}, &block)
+      return yield if amount.zero? # Skip ledger for free operations
+
+      # Check available balance (cached)
+      raise InsufficientFundsError, "Insufficient tokens" if owner.cached_balance < amount
+
+      reservation_id = nil
+      result = nil
+
+      begin
+        # Step 1: Reserve tokens (atomic, inside DB transaction)
+        reservation_id = reserve(
+          owner: owner,
+          amount: amount,
+          description: "Reserve: #{description}",
+          metadata: metadata
+        )
+
+        # Step 2: Execute external API (OUTSIDE transaction - cannot rollback)
+        result = block.call
+
+        # Step 3: Capture reserved tokens (mark as consumed)
+        capture(
+          reservation_id: reservation_id,
+          description: "Capture: #{description}",
+          metadata: metadata
+        )
+
+        result
+      rescue => e
+        # Step 3b: Release reserved tokens on failure
+        release(
+          reservation_id: reservation_id,
+          description: "Release: #{description}",
+          metadata: metadata.merge(error: e.message)
+        ) if reservation_id
+
+        raise e # Re-raise to maintain error flow
+      end
+    end
+
+    # Reserve tokens (move from wallet to reserved)
+    def self.reserve(owner:, amount:, description:, metadata: {})
+      record_transaction(
+        type: "reserve",
+        description: description,
+        owner: owner,
+        metadata: metadata,
+        entries: [
+          {
+            account_code: "wallet:#{owner.id}",
+            account_name: "User #{owner.id} Wallet",
+            type: :credit,
+            amount: amount,
+            enforce_positive: true # No overdraft
+          },
+          {
+            account_code: "wallet:#{owner.id}:reserved",
+            account_name: "User #{owner.id} Reserved",
+            type: :debit,
+            amount: amount
+          }
+        ]
+      )
+    end
+
+    # Capture reserved tokens (mark as consumed)
+    def self.capture(reservation_id:, amount: nil, description:, external_source: nil, external_id: nil, metadata: {})
+      # Find and verify the reservation transaction
+      reservation = LedgerTransaction.find_by(id: reservation_id, transaction_type: "reserve")
+      raise ArgumentError, "Reservation transaction #{reservation_id} not found" unless reservation
+
+      owner = reservation.owner
+      raise ArgumentError, "Reservation has no owner" unless owner
+
+      # Get the reserved amount from the original transaction
+      reserved_entry = reservation.ledger_entries.find_by(entry_type: "debit")
+      reserved_amount = reserved_entry.amount
+
+      # Use specified amount or full reserved amount
+      capture_amount = amount || reserved_amount
+
+      # Verify we're not capturing more than was reserved
+      raise ArgumentError, "Cannot capture #{capture_amount} tokens (only #{reserved_amount} reserved)" if capture_amount > reserved_amount
+
+      record_transaction(
+        type: "capture",
+        description: description,
+        owner: owner,
+        parent_transaction_id: reservation_id,
+        external_source: external_source,
+        external_id: external_id,
+        metadata: metadata,
+        entries: [
+          {
+            account_code: "wallet:#{owner.id}:reserved",
+            account_name: "User #{owner.id} Reserved",
+            type: :credit,
+            amount: capture_amount,
+            enforce_positive: true
+          },
+          {
+            account_code: "sink:consumed",
+            account_name: "Tokens Consumed",
+            type: :debit,
+            amount: capture_amount
+          }
+        ]
+      )
+    end
+
+    # Release reserved tokens (refund to wallet)
+    def self.release(reservation_id:, amount: nil, description:, external_source: nil, external_id: nil, metadata: {})
+      # Find and verify the reservation transaction
+      reservation = LedgerTransaction.find_by(id: reservation_id, transaction_type: "reserve")
+      raise ArgumentError, "Reservation transaction #{reservation_id} not found" unless reservation
+
+      owner = reservation.owner
+      raise ArgumentError, "Reservation has no owner" unless owner
+
+      # Get the reserved amount from the original transaction
+      reserved_entry = reservation.ledger_entries.find_by(entry_type: "debit")
+      reserved_amount = reserved_entry.amount
+
+      # Use specified amount or full reserved amount
+      release_amount = amount || reserved_amount
+
+      # Verify we're not releasing more than was reserved
+      raise ArgumentError, "Cannot release #{release_amount} tokens (only #{reserved_amount} reserved)" if release_amount > reserved_amount
+
+      record_transaction(
+        type: "release",
+        description: description,
+        owner: owner,
+        parent_transaction_id: reservation_id,
+        external_source: external_source,
+        external_id: external_id,
+        metadata: metadata,
+        entries: [
+          {
+            account_code: "wallet:#{owner.id}:reserved",
+            account_name: "User #{owner.id} Reserved",
+            type: :credit,
+            amount: release_amount,
+            enforce_positive: true
+          },
+          {
+            account_code: "wallet:#{owner.id}",
+            account_name: "User #{owner.id} Wallet",
+            type: :debit,
+            amount: release_amount
+          }
+        ]
+      )
+    end
+
+    # Adjust/Reverse a transaction by posting opposite entries
+    # Used for corrections, reversals, and manual adjustments
+    def self.adjust(owner:, entries:, description:, external_source: nil, external_id: nil, metadata: {})
+      record_transaction(
+        type: "adjustment",
+        description: description,
+        owner: owner,
+        external_source: external_source,
+        external_id: external_id,
+        metadata: metadata,
+        entries: entries
+      )
+    end
+
+    # Low-level transaction creation with row-level locking
+    def self.record_transaction(type:, description:, entries:, owner: nil, parent_transaction_id: nil, external_source: nil, external_id: nil, metadata: {})
+      logger.info "TokenLedger::Manager.record_transaction called - Type: #{type}, Owner: #{owner&.class&.name}##{owner&.id}, External: #{external_source}/#{external_id}"
+
+      ActiveRecord::Base.transaction do
+        # Verify entries balance
+        debits = entries.select { |e| e[:type] == :debit }.sum { |e| e[:amount] }
+        credits = entries.select { |e| e[:type] == :credit }.sum { |e| e[:amount] }
+
+        logger.info "Debits: #{debits}, Credits: #{credits}"
+
+        raise ImbalancedTransactionError, "Debits (#{debits}) != Credits (#{credits})" if debits != credits
+        raise ImbalancedTransactionError, "Transaction must have entries" if debits.zero? && credits.zero?
+
+        # Check for duplicate external transaction
+        if external_source && external_id
+          existing = LedgerTransaction.find_by(external_source: external_source, external_id: external_id)
+          if existing
+            logger.warn "Duplicate transaction found: #{external_source}/#{external_id}"
+            raise DuplicateTransactionError, "Duplicate transaction detected: #{external_source}/#{external_id}"
+          end
+          logger.info "No duplicate found for #{external_source}/#{external_id}"
+        end
+
+        # Create transaction
+        logger.info "Creating LedgerTransaction..."
+        txn = LedgerTransaction.create!(
+          transaction_type: type,
+          description: description,
+          owner: owner,
+          parent_transaction_id: parent_transaction_id,
+          external_source: external_source,
+          external_id: external_id,
+          metadata: metadata
+        )
+        logger.info "LedgerTransaction created: #{txn.id}"
+
+        # Create entries with row-level locking and balance updates
+        entries.each do |entry_data|
+          account = Account.find_or_create(
+            code: entry_data[:account_code],
+            name: entry_data[:account_name]
+          )
+
+          # Lock account row for update (prevents race conditions)
+          account.lock!
+
+          # Calculate new balance
+          balance_delta = case entry_data[:type]
+                         when :debit then entry_data[:amount]
+                         when :credit then -entry_data[:amount]
+                         end
+
+          new_balance = account.current_balance + balance_delta
+
+          # Enforce no overdraft (unless explicitly allowed)
+          if entry_data[:enforce_positive] && new_balance < 0
+            raise InsufficientFundsError, "Account #{account.code} would go negative (balance: #{account.current_balance}, delta: #{balance_delta})"
+          end
+
+          # Update account balance atomically
+          account.update_column(:current_balance, new_balance)
+
+          # Create ledger entry
+          LedgerEntry.create!(
+            account: account,
+            ledger_transaction: txn,
+            entry_type: entry_data[:type].to_s,
+            amount: entry_data[:amount],
+            metadata: entry_data[:metadata] || {}
+          )
+        end
+
+        # Update user cached balance if wallet affected
+        if owner && owner.respond_to?(:cached_balance)
+          wallet_account = LedgerAccount.find_by(code: "wallet:#{owner.id}")
+          if wallet_account
+            logger.info "Updating cached_balance for #{owner.class.name}##{owner.id}: #{wallet_account.current_balance}"
+            owner.update_column(:cached_balance, wallet_account.current_balance)
+            owner.broadcast_balance if owner.respond_to?(:broadcast_balance)
+          end
+        end
+
+        logger.info "Transaction #{txn.id} completed successfully"
+        txn.id
+      end
+    end
+
+    def self.logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        @logger ||= begin
+          fallback_logger = Logger.new($stdout)
+          fallback_logger.level = Logger::WARN
+          fallback_logger
+        end
+      end
+    end
+    private_class_method :logger
+  end
+end

data/lib/token_ledger/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TokenLedger
+  VERSION = "0.1.0"
+end

data/lib/token_ledger.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support"
+
+require_relative "token_ledger/version"
+require_relative "token_ledger/errors"
+require_relative "token_ledger/models/ledger_account"
+require_relative "token_ledger/models/ledger_transaction"
+require_relative "token_ledger/models/ledger_entry"
+require_relative "token_ledger/services/account"
+require_relative "token_ledger/services/balance"
+require_relative "token_ledger/services/manager"
+
+module TokenLedger
+end

data/sig/token_ledger.rbs

@@ -0,0 +1,4 @@
+module TokenLedger
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end