wallets 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30525c4168fc4fe526a19f8b53b07726accd6351867a03a3b1d91ca4b94d7355
-  data.tar.gz: 8a6d11d3cdae5ddec055ac6b6f4a8028f7ab17a6913f1395813911b4243fea41
+  metadata.gz: b8c10aa620f150ee7dc1a6da70a740d509a65d50616d6c4e382eb7abec1b15b6
+  data.tar.gz: e83766be64655b05bd0cf2a61b370bafbb15294ee8334d810b4a48bcc01136ca
 SHA512:
-  metadata.gz: 066b9709bc06269facf1f86026f2f20d8759753e42e6eb5cb052e22002a0ad4e163b416c81458ff24485ce79e9e90c7a17c7edc70b42bbdcf703c9ecfc501ae8
-  data.tar.gz: b8b6aa97479b61fa96c150de76926ed388c29996de9e01eac84f1e0f5d6108fb3fa381c6f938dbb75c51432d70c42b6c513516369c5b176ddcb66fa6f23e41e0
+  metadata.gz: '08cb2c92d219c9f1df67bb7536b3a5bb5e259489a48a882fe3ac58a95b264ddf5818a06493da4c4074df1c00799171ea46c93825be414a662fd95d1bb8562a21'
+  data.tar.gz: 2e567d9f49aef131682cfb4d1bc47d4fb96a8bfcc9c2e5f337549baf19a57e3b820300bf4105083139751f248900a50f9dbd0c018bbeadc76340b997e2cdb517

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.5.0] - 2026-10-25
+
+### Added
+
+- **Idempotency keys.** `credit`, `debit`, `transfer_to`, `hold`, `reserve` and `Hold#capture!` take `idempotency_key:`. The first call stores the key on the row it writes (the transaction, the transfer's outbound leg, the hold, or the capture's debit). A retry with the same key returns that row and posts nothing: no second posting, no callbacks, and no `InvalidHold` for a reservation the first call already captured. The same key for a different amount, category or target raises the new `Wallets::IdempotencyConflict` and writes nothing. Keys are unique per wallet among its transactions and among its holds, so a reservation and its capture can share one. The lookup runs under the wallet lock (a current read when a MySQL snapshot is stale), so concurrent duplicates post once, and a unique index on `(wallet_id, idempotency_key)` backs it up. `release!` needs no key: it was already idempotent. Asked for by ReplyBrain, whose at-least-once jobs reserve an estimate and capture the actual cost.
+
+### Upgrading
+
+- Run `rails generate wallets:upgrade` and `rails db:migrate`. The generator now writes `add_wallets_idempotency_keys`, which adds a nullable `idempotency_key` string and a unique `(wallet_id, idempotency_key)` index to the transactions and holds tables; it is a no-op where they exist, and fresh installs get them from `wallets:install`. Until it has run, a command given a key raises `Wallets::Error`; commands without a key work exactly as before. Embedded ledgers opt in by adding the same column and index to their own tables.
+
 ## [0.4.3] - 2026-10-19
 
 ### Fixed

data/README.md

@@ -293,6 +293,27 @@ user.wallet(:coins).credit(
 
 Debits consume the soonest-expiring credits first, then the oldest. Expired value is never spent, and neither is held value (see [Holds and reservations](#holds-and-reservations)).
 
+### Retries and idempotency keys
+
+Webhooks arrive twice and jobs run again. Give a command an `idempotency_key:` and it posts once, however many times it runs:
+
+```ruby
+wallet.credit(5_000, category: :top_up, idempotency_key: "stripe:#{invoice.id}")
+wallet.credit(5_000, category: :top_up, idempotency_key: "stripe:#{invoice.id}") # => the same transaction, nothing added
+```
+
+`credit`, `debit`, `transfer_to`, `hold`, `reserve` and `capture!` all take one. The first call stores the key on the row it writes. A retry with the same key returns that row: no second posting, no callbacks, not even an `InvalidHold` for a reservation the first call already captured. That makes the reserve-then-capture pattern safe in an at-least-once job:
+
+```ruby
+reservation = wallet.reserve(estimate, category: :run, idempotency_key: "run:#{run.id}")
+# ... do the work ...
+reservation.capture!(actual, category: :run, idempotency_key: "run:#{run.id}")
+```
+
+Keys are unique per wallet, once among its transactions and once among its holds, so a reservation and its capture can share one. A retry must ask for the same thing: the same amount, category and target (the recipient of a transfer, the credit a hold covers, the reservation a capture charges). The same key for anything else raises `Wallets::IdempotencyConflict` and writes nothing. Metadata, deadlines and expirations are the first call's, so a retry that recomputes `1.hour.from_now` is still a retry. A command that failed or rolled back stored no key, so its retry runs for real. `release!` needs no key: releasing a hold that already ended does nothing.
+
+Duplicates that run at the same moment queue on the wallet's row lock, and the second one finds the first one's row. A unique index on `(wallet_id, idempotency_key)` backs that up in the database.
+
 ## Holds and reservations
 
 Sometimes value is in a wallet but must not be spent yet. A reward waits for validation. A seller's earnings wait out the return window. A booking sets money aside until the service is delivered. A fraud review freezes one credit, or the whole wallet. `wallets` models all of these with **holds**, and reads them the way your bank statement does:
@@ -554,7 +575,7 @@ rails db:migrate
 
 > **Migrate before the 0.4.0 code serves traffic.** The new code expects the holds table and the wallets' `ledger_revision` column. Until `rails db:migrate` has added them, reading a `Wallets::Wallet`'s balance, or running any command on it (an initial balance included), raises: a ledger that keeps holds fails loudly on purpose rather than treat held value as spendable. Deploy the migration first, then the code.
 
-The upgrade generator writes one migration that adds the holds table, and a `ledger_revision` column on the wallets table, to a 0.1, 0.2 or 0.3 install. It follows your `table_prefix`, and reads the key types from the tables you already have, uuid and unsigned keys included. Running it again never writes a second migration, and it writes none at all when both already exist. Rolling the migration back removes them only while the holds table is empty. Fresh installs get both from `rails generate wallets:install`.
+The upgrade generator writes up to two migrations. The first adds the holds table, and a `ledger_revision` column on the wallets table, to a 0.1, 0.2 or 0.3 install. The second adds the `idempotency_key` columns and their unique indexes (0.5) to any earlier install; until it has run, a command given a key raises instead of ignoring it, and commands without one work as before. It follows your `table_prefix`, and reads the key types from the tables you already have, uuid and unsigned keys included. Running it again never writes a duplicate, and it writes neither migration when the schema already has what it adds. Rolling the migration back removes them only while the holds table is empty. Fresh installs get both from `rails generate wallets:install`.
 
 Then look at where your app reads `wallet.balance`. It still means "what can be spent", so spending checks need no change. Screens and reports that mean "everything the user has", such as a total earned, should read `total_balance`. A reconciliation of the cached `balance` column compares it with `wallet.balance`, never with `total_balance`: the column stores the available balance, so reserving 30 of 100 leaves it at 70 while `total_balance` reads 100. Even then the two can differ through time alone, as credits expire and deadlines pass.
 
@@ -595,6 +616,7 @@ end
 - If your wallets can be destroyed, destroy their holds first. `Wallets::Wallet` does it in a `before_destroy` callback declared with `prepend: true`, so the holds go before the transactions they point at.
 - If you override `current_balance`, decide on purpose how it treats held and reserved value. With holds on, `balance`, `held_balance` and `total_balance` come from one set of terms. Overriding `current_balance` alone can break `total_balance == balance + held_balance`, so keep all three coherent.
 - `credit` now takes the keywords `hold:` and `available_at:`, and `debit` takes `from:`. If your transaction table has columns by those names, you can no longer pass them through `credit` or `debit` as extra attributes.
+- To accept idempotency keys, add a `string :idempotency_key` column and a unique index on `(wallet_id, idempotency_key)` to your transactions table, and to your holds table if you keep holds. A ledger without the column raises when a command is given a key, and works as before without one.
 
 ### Performance and concurrency
 

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Adds idempotency keys (wallets 0.5) to an existing installation: a key on
+# transactions and on holds, unique per wallet, so a retried command returns
+# what it posted the first time instead of posting again.
+class AddWalletsIdempotencyKeys < ActiveRecord::Migration<%= migration_version %>
+  def up
+    [transactions_table, holds_table].each do |table|
+      next unless table_exists?(table)
+
+      add_column table, :idempotency_key, :string unless column_exists?(table, :idempotency_key)
+      unless index_exists?(table, [:wallet_id, :idempotency_key], unique: true)
+        add_index table, [:wallet_id, :idempotency_key], unique: true, name: index_name(table)
+      end
+    end
+  end
+
+  # The keys only recognise retries: dropping them loses no value, only the
+  # ability to tell a retry from a new command.
+  def down
+    [transactions_table, holds_table].each do |table|
+      next unless table_exists?(table) && column_exists?(table, :idempotency_key)
+
+      remove_index table, name: index_name(table) if index_name_exists?(table, index_name(table))
+      remove_column table, :idempotency_key
+    end
+  end
+
+  private
+
+  def table_prefix
+    Wallets.configuration.table_prefix
+  end
+
+  def transactions_table
+    "#{table_prefix}transactions"
+  end
+
+  def holds_table
+    "#{table_prefix}holds"
+  end
+
+  # The names the install template gives the same indexes.
+  def index_name(table)
+    "index_#{table}_on_wallet_and_idempotency_key"
+  end
+end

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

@@ -37,6 +37,8 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
       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)
+      # The key a retried command is recognised by, unique per wallet.
+      t.string :idempotency_key
 
       t.timestamps
     end
@@ -82,6 +84,8 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
       t.string :release_reason
       t.send(json_column_type, :metadata, null: false, default: json_column_default)
       t.send(json_column_type, :release_metadata, null: false, default: json_column_default)
+      # The key a retried hold or reservation is recognised by, unique per wallet.
+      t.string :idempotency_key
 
       t.timestamps
 
@@ -92,6 +96,7 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
       t.index [:wallet_id, :released_at], name: index_name("holds_on_wallet_and_released_at")
       t.index [:transaction_id, :released_at], name: index_name("holds_on_tx_and_released_at")
       t.index :releases_at, name: index_name("holds_on_releases_at")
+      t.index [:wallet_id, :idempotency_key], unique: true, name: index_name("holds_on_wallet_and_idempotency_key")
 
       t.check_constraint "amount IS NULL OR amount > 0", name: constraint_name("holds_amount_positive")
       # A credit hold holds the credit's whole remaining value, never an amount.
@@ -118,6 +123,7 @@ class CreateWalletsTables < ActiveRecord::Migration<%= migration_version %>
     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, [:wallet_id, :idempotency_key], unique: true, name: index_name("transactions_on_wallet_and_idempotency_key")
     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")

data/lib/generators/wallets/upgrade_generator.rb

@@ -5,8 +5,9 @@ require "rails/generators/active_record"
 
 module Wallets
   module Generators
-    # Brings an existing installation's schema up to date. Today that is one
-    # migration: the holds table that 0.4 adds to 0.1, 0.2 and 0.3 installs.
+    # Brings an existing installation's schema up to date: the holds table
+    # that 0.4 adds to 0.1, 0.2 and 0.3 installs, and the idempotency keys
+    # that 0.5 adds to every earlier install.
     class UpgradeGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
@@ -26,25 +27,42 @@ module Wallets
         existing_migration = self.class.migration_exists?(File.expand_path(db_migrate_path, destination_root), "add_wallets_holds")
 
         if existing_migration
+          @pending = true
           say_status :exist, relative_to_original_destination_root(existing_migration), :blue
         elsif upgraded_schema?
-          @skipped = true
           say_status :skip, "#{holds_table} already exists: there is nothing to migrate", :yellow
         else
+          @pending = true
           migration_template "add_wallets_holds.rb.erb", File.join(db_migrate_path, "add_wallets_holds.rb")
         end
       end
 
+      # Idempotent in the same way: written once, and only for a schema
+      # whose transactions do not have their key yet.
+      def create_idempotency_keys_migration
+        existing_migration = self.class.migration_exists?(File.expand_path(db_migrate_path, destination_root), "add_wallets_idempotency_keys")
+
+        if existing_migration
+          @pending = true
+          say_status :exist, relative_to_original_destination_root(existing_migration), :blue
+        elsif keyed_schema?
+          say_status :skip, "#{transactions_table} already has idempotency keys: there is nothing to migrate", :yellow
+        else
+          @pending = true
+          migration_template "add_wallets_idempotency_keys.rb.erb", File.join(db_migrate_path, "add_wallets_idempotency_keys.rb")
+        end
+      end
+
       def display_post_upgrade_message
-        if @skipped
-          say "\n✅ This app already has the `wallets` 0.4 holds table: nothing to migrate.", :green
+        unless @pending
+          say "\n✅ This app already has the latest `wallets` schema: nothing to migrate.", :green
           say "\nRead the 0.4.0 CHANGELOG: `balance` is now the AVAILABLE balance, and held value is excluded from it."
           return
         end
 
-        say "\n🎉 The `wallets` upgrade migration is ready.", :green
+        say "\n🎉 The `wallets` upgrade migrations are ready.", :green
         say "\nTo complete the upgrade:"
-        say "  1. Run 'rails db:migrate' to add the holds table (a no-op if it already exists)."
+        say "  1. Run 'rails db:migrate' to add the holds table and the idempotency keys (each a no-op if already there)."
         say "  2. Read the 0.4.0 CHANGELOG: `balance` is now the AVAILABLE balance, and held value is excluded from it."
       end
 
@@ -60,10 +78,24 @@ module Wallets
         false
       end
 
+      # Same rule: a database that cannot be asked gets the migration.
+      def keyed_schema?
+        ActiveRecord::Base.with_connection do |connection|
+          connection.column_exists?(transactions_table, :idempotency_key) &&
+            (!connection.table_exists?(holds_table) || connection.column_exists?(holds_table, :idempotency_key))
+        end
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
       def holds_table
         "#{Wallets.configuration.table_prefix}holds"
       end
 
+      def transactions_table
+        "#{Wallets.configuration.table_prefix}transactions"
+      end
+
       def wallets_table
         "#{Wallets.configuration.table_prefix}wallets"
       end

data/lib/wallets/models/hold.rb

@@ -162,12 +162,16 @@ module Wallets
     # funded at the moment it happens: value a hold covers is not spent, and
     # unless overdrafts are on a capture the wallet cannot fund raises
     # Wallets::InsufficientBalance and leaves the reservation as it was.
-    def capture!(amount = nil, category:, metadata: {})
+    #
+    # With `idempotency_key:` a retried capture returns the debit it posted
+    # the first time instead of raising, so an at-least-once job can simply
+    # run again (see `Wallets::WalletBase#credit`).
+    def capture!(amount = nil, category:, metadata: {}, idempotency_key: nil)
       raise InvalidHold, "Only a saved reservation can be captured" unless persisted?
 
       # The wallet runs the capture: it takes its own lock before reading
       # this reservation, the same order as every other command.
-      wallet.send(:capture_reservation!, self, amount, category: category, metadata: metadata)
+      wallet.send(:capture_reservation!, self, amount, category: category, metadata: metadata, idempotency_key: idempotency_key)
     end
 
     private

data/lib/wallets/models/wallet.rb

@@ -37,6 +37,7 @@ module Wallets
     CORE_TRANSACTION_ATTRIBUTE_NAMES = %i[
       id wallet wallet_id amount category expires_at metadata transfer
       transfer_id balance_before balance_after created_at updated_at
+      idempotency_key
     ].freeze
 
     # Plain SELECTs on these adapters may answer from a stale snapshot inside
@@ -381,29 +382,42 @@ module Wallets
     #   wallet.credit(751, category: :reward, hold: :pending_validation)
     #   wallet.credit(751, category: :reward, hold: {category: :pending_validation, until: 3.months.from_now, metadata: {ride_id: 7}})
     #   wallet.credit(500, category: :reward, available_at: 14.days.from_now) # held as :pending until then
-    def credit(amount, metadata: {}, category: :credit, expires_at: nil, transfer: nil, hold: nil, available_at: nil, **extra_transaction_attributes)
+    #
+    # Every command that posts takes an `idempotency_key:`. The first call
+    # with a key posts and stores the key on the row it writes; a retry with
+    # the same key returns that row and posts nothing, so a job that runs
+    # twice charges once. The same key for a different command raises
+    # Wallets::IdempotencyConflict.
+    #
+    #   wallet.credit(500, category: :top_up, idempotency_key: "stripe:#{invoice.id}")
+    def credit(amount, metadata: {}, category: :credit, expires_at: nil, transfer: nil, hold: nil, available_at: nil, idempotency_key: nil, **extra_transaction_attributes)
       metadata = normalize_metadata(metadata)
       extra_transaction_attributes = validate_additional_transaction_attributes!(extra_transaction_attributes)
       arrival_hold = arrival_hold_attributes(hold, available_at)
+      idempotency_key = normalize_idempotency_key!(idempotency_key, transaction_class)
 
       # A savepoint even inside a caller's transaction, like every command: a
       # credit that cannot get its hold must not survive as a spendable credit
       # because the caller rescued the error and committed.
       with_lock(requires_new: true) do
         mutating_at(Time.current) do
-          # Value that becomes available at an instant already reached is
-          # simply available: there is nothing left to hold.
-          arrival_hold = nil if available_at && arrival_hold[:releases_at] <= evaluation_time
-
-          apply_credit(
-            amount,
-            metadata: metadata,
-            category: category,
-            expires_at: expires_at,
-            transfer: transfer,
-            extra_attributes: extra_transaction_attributes,
-            hold: arrival_hold
-          )
+          same_credit = ->(earlier) { earlier.amount == normalize_positive_amount!(amount) && earlier.category == category.to_s && earlier.transfer_id == transfer&.id }
+
+          once_per_key(idempotency_key, transaction_class, same: same_credit) do
+            # Value that becomes available at an instant already reached is
+            # simply available: there is nothing left to hold.
+            arrival_hold = nil if available_at && arrival_hold[:releases_at] <= evaluation_time
+
+            apply_credit(
+              amount,
+              metadata: metadata,
+              category: category,
+              expires_at: expires_at,
+              transfer: transfer,
+              extra_attributes: extra_transaction_attributes.merge(keyed(idempotency_key)),
+              hold: arrival_hold
+            )
+          end
         end
       end
     end
@@ -426,20 +440,27 @@ module Wallets
     # with overdrafts off, what it takes from unheld credits must fit in the
     # available balance, so naming an unheld credit cannot spend value that a
     # reservation set aside, nor deepen a deficit.
-    def debit(amount, metadata: {}, category: :debit, transfer: nil, from: ELIGIBLE_CREDITS, **extra_transaction_attributes)
+    def debit(amount, metadata: {}, category: :debit, transfer: nil, from: ELIGIBLE_CREDITS, idempotency_key: nil, **extra_transaction_attributes)
       metadata = normalize_metadata(metadata)
       extra_transaction_attributes = validate_additional_transaction_attributes!(extra_transaction_attributes)
       sources = named_credits(from)
+      idempotency_key = normalize_idempotency_key!(idempotency_key, transaction_class)
 
       with_lock(requires_new: true) do
-        apply_debit(
-          amount,
-          metadata: metadata,
-          category: category,
-          transfer: transfer,
-          extra_attributes: extra_transaction_attributes,
-          from: sources
-        )
+        mutating_at(Time.current) do
+          same_debit = ->(earlier) { earlier.amount == -normalize_positive_amount!(amount) && earlier.category == category.to_s && earlier.transfer_id == transfer&.id && !capture?(earlier) }
+
+          once_per_key(idempotency_key, transaction_class, same: same_debit) do
+            apply_debit(
+              amount,
+              metadata: metadata,
+              category: category,
+              transfer: transfer,
+              extra_attributes: extra_transaction_attributes.merge(keyed(idempotency_key)),
+              from: sources
+            )
+          end
+        end
       end
     end
 
@@ -458,7 +479,7 @@ module Wallets
     #
     # Only leaving the credit out holds the whole wallet: an explicit nil
     # (a credit that was looked up and not found) is refused.
-    def hold(credit = WHOLE_WALLET, category:, until: nil, metadata: {})
+    def hold(credit = WHOLE_WALLET, category:, until: nil, metadata: {}, idempotency_key: nil)
       ensure_holds_enabled!
       raise ArgumentError, "Pass no credit to hold the whole wallet; nil is not a credit" if credit.nil?
 
@@ -467,15 +488,20 @@ module Wallets
       # `until` is a Ruby keyword: the argument reads as plain English at the
       # call site, and the binding is the only way to reach it in here.
       releases_at = normalize_deadline(binding.local_variable_get(:until))
+      idempotency_key = normalize_idempotency_key!(idempotency_key, hold_class)
 
       with_lock(requires_new: true) do
         mutating_at(Time.current) do
-          # The target first: a wrong argument is a wrong argument, whatever
-          # the deadline says.
-          ensure_holdable!(credit) unless credit.nil?
-          ensure_deadline_ahead!(releases_at)
+          same_hold = ->(earlier) { earlier.coverage? && earlier.transaction_id == credit&.id && earlier.category == category.to_s.strip }
+
+          once_per_key(idempotency_key, hold_class, same: same_hold) do
+            # The target first: a wrong argument is a wrong argument, whatever
+            # the deadline says.
+            ensure_holdable!(credit) unless credit.nil?
+            ensure_deadline_ahead!(releases_at)
 
-          place_hold!(credit: credit, category: category, releases_at: releases_at, metadata: metadata)
+            place_hold!(credit: credit, category: category, releases_at: releases_at, metadata: metadata, **keyed(idempotency_key))
+          end
         end
       end
     end
@@ -485,22 +511,33 @@ module Wallets
     # must fit in `balance` unless `allow_negative_balance` is on.
     #
     #   wallet.reserve(3_000, category: :booking, until: 7.days.from_now, metadata: {booking_id: 9})
-    def reserve(amount, category:, until: nil, metadata: {})
+    #
+    # A reservation made from a job that may run twice takes a key, and so
+    # does its capture (see `credit`):
+    #
+    #   reservation = wallet.reserve(estimate, category: :run, idempotency_key: "run:#{run.id}")
+    #   reservation.capture!(actual, category: :run, idempotency_key: "run:#{run.id}")
+    def reserve(amount, category:, until: nil, metadata: {}, idempotency_key: nil)
       ensure_holds_enabled!
       amount = normalize_positive_amount!(amount)
       metadata = normalize_metadata(metadata)
       releases_at = normalize_deadline(binding.local_variable_get(:until))
+      idempotency_key = normalize_idempotency_key!(idempotency_key, hold_class)
 
       with_lock(requires_new: true) do
         mutating_at(Time.current) do
-          ensure_deadline_ahead!(releases_at)
-          available = balance
+          same_reservation = ->(earlier) { earlier.amount == amount && earlier.category == category.to_s.strip }
 
-          if amount > available && !allow_negative_balance?
-            reject_insufficient_balance!(amount, available, metadata)
-          end
+          once_per_key(idempotency_key, hold_class, same: same_reservation) do
+            ensure_deadline_ahead!(releases_at)
+            available = balance
+
+            if amount > available && !allow_negative_balance?
+              reject_insufficient_balance!(amount, available, metadata)
+            end
 
-          place_hold!(amount: amount, category: category, releases_at: releases_at, metadata: metadata, previous_balance: available)
+            place_hold!(amount: amount, category: category, releases_at: releases_at, metadata: metadata, previous_balance: available, **keyed(idempotency_key))
+          end
         end
       end
     end
@@ -514,7 +551,11 @@ module Wallets
     # held value included, and the inbound legs are credited as usual.
     #
     #   wallet.transfer_to(platform.wallet, 751, category: :reversal, from: credit)
-    def transfer_to(other_wallet, amount, category: :transfer, metadata: {}, expiration_policy: nil, expires_at: nil, from: ELIGIBLE_CREDITS)
+    #
+    # With `idempotency_key:` a retried transfer returns the Transfer it made
+    # the first time (see `credit`). The key is the sender's: it is stored
+    # on the outbound leg.
+    def transfer_to(other_wallet, amount, category: :transfer, metadata: {}, expiration_policy: nil, expires_at: nil, from: ELIGIBLE_CREDITS, idempotency_key: nil)
       raise InvalidTransfer, "Target wallet is required" if other_wallet.nil?
       raise InvalidTransfer, "Source wallet must be persisted" unless persisted?
       raise InvalidTransfer, "Target wallet must be persisted" unless other_wallet.persisted?
@@ -528,6 +569,7 @@ module Wallets
       metadata = normalize_metadata(metadata)
       resolved_policy, inbound_expires_at = resolve_transfer_expiration!(expiration_policy, expires_at)
       sources = named_credits(from)
+      idempotency_key = normalize_idempotency_key!(idempotency_key, transaction_class)
 
       # A savepoint even inside a caller's transaction, like every command: a
       # transfer whose inbound leg fails must take its outbound debit and its
@@ -538,6 +580,14 @@ module Wallets
 
         # The recipient pins the same instant in its own `apply_credit`.
         mutating_at(now) do
+          same_transfer = ->(earlier) {
+            sent = earlier.transfer
+            earlier.category == "transfer_out" && sent.present? &&
+              sent.to_wallet_id == other_wallet.id && sent.amount == amount && sent.category == category.to_s
+          }
+          earlier = earlier_command(idempotency_key, transaction_class, same: same_transfer)
+          next earlier.transfer if earlier
+
           previous_balance = balance
 
           # Insufficient-balance gate.
@@ -620,6 +670,7 @@ module Wallets
 
           _outbound_transaction, allocations = apply_debit_with_allocations(
             amount,
+            extra_attributes: keyed(idempotency_key),
             category: :transfer_out,
             metadata: shared_metadata.merge(
               "counterparty_wallet_id" => other_wallet.id,
@@ -1270,14 +1321,27 @@ module Wallets
     # the callbacks report are the ones before and after the whole step,
     # never the instant in between where the reservation is gone and the
     # debit not yet posted: capturing a fully reserved wallet reads 0 -> 0.
-    def capture_reservation!(reservation, amount, category:, metadata:)
+    #
+    # A capture with a key looks for it before anything else, so that the
+    # retry of a capture that went through returns its debit rather than
+    # raising Wallets::InvalidHold for the reservation it already ended.
+    def capture_reservation!(reservation, amount, category:, metadata:, idempotency_key: nil)
       metadata = normalize_metadata(metadata)
+      idempotency_key = normalize_idempotency_key!(idempotency_key, transaction_class)
 
       ending_hold(reservation) do
         mutating_at(Time.current) do
           # A locking read: the reservation as it is now, whatever an earlier
           # read in this transaction saw.
           reservation.lock!
+
+          same_capture = ->(earlier) {
+            earlier.id == reservation.capture_transaction_id && earlier.category == category.to_s &&
+              (amount.nil? || earlier.amount == -normalize_positive_amount!(amount))
+          }
+          earlier = earlier_command(idempotency_key, transaction_class, same: same_capture)
+          next earlier if earlier
+
           ensure_capturable!(reservation)
           amount = capture_amount(reservation, amount)
 
@@ -1293,7 +1357,7 @@ module Wallets
           # With overdrafts on, a capture beyond the eligible credits leaves
           # exactly the rest unbacked; one within them leaves no debt at all,
           # however underfunded the other reservations end up.
-          debit, _allocations = post_debit!(amount, metadata: metadata, category: category, transfer: nil, allow_unbacked: allow_negative_balance?)
+          debit, _allocations = post_debit!(amount, metadata: metadata, category: category, transfer: nil, extra_attributes: keyed(idempotency_key), allow_unbacked: allow_negative_balance?)
           reservation.update!(released_at: evaluation_time, release_reason: "captured", capture_transaction: debit)
           new_balance = refresh_cached_balance!
 
@@ -1339,6 +1403,69 @@ module Wallets
       end
     end
 
+    # =========================================
+    # Idempotency Keys
+    # =========================================
+
+    # The key a command was given, ready to look up and store: nil for none,
+    # a non-blank string otherwise. A ledger whose table has no
+    # `idempotency_key` column (an embedder's, or an install that has not
+    # run `rails g wallets:upgrade`) refuses a key rather than ignore it: a
+    # key that is silently dropped would let a retry post twice.
+    def normalize_idempotency_key!(key, model)
+      return if key.nil?
+
+      key = key.to_s
+      raise ArgumentError, "idempotency_key can't be blank" if key.strip.empty?
+      unless model.column_names.include?("idempotency_key")
+        raise Error, "#{model.table_name} has no idempotency_key column: run `rails g wallets:upgrade` and migrate to use idempotency keys"
+      end
+
+      key
+    end
+
+    # The attributes that store a key on the row a command writes.
+    def keyed(idempotency_key)
+      idempotency_key.nil? ? {} : {idempotency_key: idempotency_key}
+    end
+
+    # Runs a command once per key: the row an earlier call with this key
+    # posted, or whatever the block posts now.
+    def once_per_key(idempotency_key, model, same:)
+      earlier_command(idempotency_key, model, same: same) || yield
+    end
+
+    # The row this wallet already posted under `idempotency_key`, if any.
+    # Read under the wallet lock at the command's instant, as a current read
+    # when the snapshot is stale (see `stale_snapshot?`): every command on
+    # this wallet queues on that lock, so a duplicate running at the same
+    # time waits for the first to commit and then finds its row. The unique
+    # index on (wallet_id, idempotency_key) is the backstop.
+    #
+    # `same` tells a retry from a different command that reuses the key: the
+    # amount, the category and what the command acts on must match. Metadata,
+    # deadlines and expirations are the first call's, so a retry that
+    # recomputes `7.days.from_now` is still a retry.
+    def earlier_command(idempotency_key, model, same:)
+      return if idempotency_key.nil?
+
+      earlier = current_read(model.where(wallet_id: id, idempotency_key: idempotency_key), current_reads?).take
+      return if earlier.nil?
+
+      unless same.call(earlier)
+        raise IdempotencyConflict, "Idempotency key #{idempotency_key.inspect} was already used on wallet #{id} " \
+          "for a different command (#{model.model_name.human.downcase} #{earlier.id})"
+      end
+
+      earlier
+    end
+
+    # Whether a debit is a reservation's capture: a plain debit's key must
+    # not replay a capture, nor the other way round.
+    def capture?(debit)
+      holds_enabled? && hold_class.where(capture_transaction_id: debit.id).exists?
+    end
+
     # A credit can be held when it is a saved credit of this very wallet and
     # ledger, still unexpired at the command's instant, with value left to
     # hold. Read from the database under the wallet lock, never from the

data/lib/wallets/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wallets
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

data/lib/wallets.rb

@@ -21,6 +21,8 @@ module Wallets
   class InvalidTransfer < Error; end
   class InvalidHold < Error; end
   class HoldsNotEnabled < Error; end
+  # An idempotency key the wallet already used for a different command.
+  class IdempotencyConflict < Error; end
 
   class << self
     attr_writer :configuration

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: wallets
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-10-18 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -46,6 +46,7 @@ files:
 - README.md
 - lib/generators/wallets/install_generator.rb
 - lib/generators/wallets/templates/add_wallets_holds.rb.erb
+- lib/generators/wallets/templates/add_wallets_idempotency_keys.rb.erb
 - lib/generators/wallets/templates/create_wallets_tables.rb.erb
 - lib/generators/wallets/templates/initializer.rb
 - lib/generators/wallets/upgrade_generator.rb