bsv-wallet-postgres 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9afef26a167d09125962a45afc6d24d0233de215847c34233346fc1dbba11f34
-  data.tar.gz: 453a4d2d63f1735beae93aeb4e32ef37c9a15ab09141865a7789b736824b4507
+  metadata.gz: cc93b503d2d084ed5b1221f97803f66b171141f2c8a855b7c247b0a54b434fc3
+  data.tar.gz: 55b88e4b7a82168df0da8b38ace070fbc50d76249e08e4aa35aaa49bb09a199f
 SHA512:
-  metadata.gz: 600ceec193391521686eae2a52201e905cd9d9ac495a07060747eb7e3b97b5d8bf1172774d1b67f16d15328d94e51e20eab2c1afd13c7e7042221f053fd99537
-  data.tar.gz: 60925f55c22d87445398817f1368096df57b639b2e439b60e09a40ecc716c6d70abaeee49294b8bef9f30d92bf41d88906a9e45000be8ca03d6c07214733bb64
+  metadata.gz: d124ec0511c1ed69ff41a4c9e3a681d794a869a89c1439286b6bac32dc173576e63f22df86f20665a8b5d216fd2057b9245d5b1756581afe4eab6f71deea39e2
+  data.tar.gz: 62842664bdd3ad2ba4f065f0e081065baec92c30bb7ad53cfed71dd1f91135f7e8cb3a9dbea73abe9895a4ef691da5b32ccaf744b6dcc0d3a52caa4b075aedc1

data/{CHANGELOG-wallet-postgres.md → CHANGELOG.md}

@@ -5,6 +5,34 @@ All notable changes to the `bsv-wallet-postgres` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.0 — 2026-04-12
+
+### Added
+
+- **Migration 004** — adds `satoshis`, `pending_since`, `pending_reference`,
+  `no_send` columns and a partial index on `(state, basket)` for spendable
+  rows (#353)
+- **`find_spendable_outputs(basket:, min_satoshis:, sort_order:)`** — query
+  spendable outputs with backward-compatible COALESCE for legacy rows (#354)
+- **`update_output_state(outpoint, new_state, ...)`** — transition output
+  state with JSONB data synchronisation (#354)
+- **`lock_utxos(outpoints, reference:, no_send:)`** — atomic
+  `UPDATE ... WHERE state = 'spendable' RETURNING` pattern for concurrent
+  safety (#355)
+- **`release_stale_pending!(timeout:)`** — recover stuck pending outputs,
+  exempting `no_send` locks (#355)
+- **PostgresStore settings methods** — `store_setting` / `find_setting`
+
+### Fixed
+
+- **Spendable boolean sync** — `update_output_state`, `lock_utxos`, and
+  `release_stale_pending!` now keep the legacy `spendable` column in sync
+  with the `state` column; `filter_outputs` uses dual-column WHERE clause
+
+### Changed
+
+- Directory restructure — source moved to `gem/bsv-wallet-postgres/`
+
 ## 0.1.0 — 2026-04-09
 
 Initial release of `bsv-wallet-postgres`, a PostgreSQL-backed

data/lib/bsv/wallet_postgres/migrations/002_add_output_state.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Add output lifecycle state column to wallet_outputs.
+#
+# Introduces a nullable +state+ text column alongside the existing boolean
+# +spendable+ column. The two fields are kept in sync by the application
+# layer (+PostgresStore#update_output_state+).
+#
+# === State values
+#
+# * +spendable+ — the output is available for coin selection
+# * +pending+   — the output has been selected but the spending transaction
+#                 has not yet been broadcast or confirmed
+# * +spent+     — the output has been consumed by a confirmed transaction
+#
+# === Backward compatibility
+#
+# Rows written before this migration have +state = NULL+. The application
+# treats +state IS NULL AND spendable = TRUE+ as equivalent to
+# +state = 'spendable'+ so that existing data continues to behave
+# correctly without a backfill.
+#
+# The migration is intentionally non-destructive: +state+ is nullable
+# so the migration itself applies instantly on large tables (no rewrite,
+# no default scan). A backfill can be run offline if required.
+Sequel.migration do
+  change do
+    alter_table(:wallet_outputs) do
+      add_column :state, String, null: true
+      add_index :state
+    end
+  end
+end

data/lib/bsv/wallet_postgres/migrations/003_add_wallet_settings.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Add wallet settings table to BSV::Wallet::PostgresStore.
+#
+# Provides key-value persistence for wallet configuration (e.g. change
+# output parameters). Keys are short strings (e.g. 'change_params');
+# values are JSON-serialised strings so the schema never needs to change
+# when setting shapes evolve.
+#
+# The table uses +key+ as its primary key so +store_setting+ is a simple
+# upsert (insert-or-replace on conflict).
+Sequel.migration do
+  change do
+    create_table(:wallet_settings) do
+      String :key, primary_key: true
+      String :value, text: true, null: false
+      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+    end
+  end
+end

data/lib/bsv/wallet_postgres/migrations/004_add_pending_metadata.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Add pending lock metadata columns and satoshis to wallet_outputs.
+#
+# Introduces dedicated columns to support the auto-fund UTXO management
+# methods (+find_spendable_outputs+, +lock_utxos+, +update_output_state+,
+# +release_stale_pending!+) without requiring expensive JSONB extraction
+# on every query.
+#
+# === Columns added
+#
+# * +satoshis+          — bigint, nullable. Mirrors the value stored inside
+#                         the JSONB +data+ blob so that +find_spendable_outputs+
+#                         can +ORDER BY satoshis+ without casting. New writes
+#                         populate this column; existing rows leave it NULL
+#                         and queries fall back to +COALESCE(satoshis, (data->>'satoshis')::bigint, 0)+.
+#
+# * +pending_since+     — timestamp (UTC), nullable. Set to +NOW()+ when a
+#                         UTXO is locked via +lock_utxos+. Used by
+#                         +release_stale_pending!+ to identify stale locks.
+#
+# * +pending_reference+ — text, nullable. Caller-supplied label passed to
+#                         +lock_utxos+. Carried through for observability.
+#
+# * +no_send+           — boolean, default +false+. When +true+ the lock is
+#                         exempt from automatic stale recovery by
+#                         +release_stale_pending!+.
+#
+# === Index added
+#
+# A partial index on +(state, basket)+ filtered to rows where
+# +state IS NULL OR state = 'spendable'+ accelerates the hot path of
+# +find_spendable_outputs+: the vast majority of rows in a live wallet
+# are spendable, not pending or spent.
+#
+# === Backward compatibility
+#
+# All new columns are nullable (or carry a safe default). No existing rows
+# are modified. The application layer handles NULL values via +COALESCE+ or
+# explicit IS NULL checks.
+Sequel.migration do
+  up do
+    alter_table(:wallet_outputs) do
+      add_column :satoshis,          :bigint, null: true
+      add_column :pending_since,     :timestamptz, null: true
+      add_column :pending_reference, String,   null: true
+      add_column :no_send,           :boolean, null: false, default: false
+    end
+
+    # Partial index on spendable rows only — keeps the index small and
+    # fast for the typical coin-selection scan.
+    run <<~SQL
+      CREATE INDEX wallet_outputs_spendable_basket_idx
+        ON wallet_outputs (state, basket)
+        WHERE (state IS NULL OR state = 'spendable');
+    SQL
+  end
+
+  down do
+    run 'DROP INDEX IF EXISTS wallet_outputs_spendable_basket_idx;'
+
+    alter_table(:wallet_outputs) do
+      drop_column :no_send
+      drop_column :pending_reference
+      drop_column :pending_since
+      drop_column :satoshis
+    end
+  end
+end

data/lib/bsv/wallet_postgres/postgres_store.rb

@@ -109,7 +109,14 @@ module BSV
         @db[:wallet_outputs]
           .insert_conflict(
             target: :outpoint,
-            update: { basket: row[:basket], tags: row[:tags], spendable: row[:spendable], data: row[:data] }
+            update: {
+              basket: row[:basket],
+              tags: row[:tags],
+              spendable: row[:spendable],
+              state: row[:state],
+              satoshis: row[:satoshis],
+              data: row[:data]
+            }
           )
           .insert(row)
         output_data
@@ -128,6 +135,154 @@ module BSV
         @db[:wallet_outputs].where(outpoint: outpoint).delete.positive?
       end
 
+      # Returns outputs whose effective state is +:spendable+.
+      #
+      # Legacy rows with +state = NULL+ are treated as spendable when the
+      # +spendable+ boolean is true (or absent), matching MemoryStore's
+      # effective_state logic.
+      #
+      # @param basket [String, nil] restrict to this basket when provided
+      # @param min_satoshis [Integer, nil] exclude outputs below this value
+      # @param sort_order [Symbol] +:asc+ or +:desc+ (default +:desc+, largest first)
+      # @return [Array<Hash>]
+      def find_spendable_outputs(basket: nil, min_satoshis: nil, sort_order: :desc)
+        ds = @db[:wallet_outputs]
+             .where(Sequel.lit('(state = ? OR (state IS NULL AND spendable = TRUE))', 'spendable'))
+        ds = ds.where(basket: basket) if basket
+        if min_satoshis
+          ds = ds.where(
+            Sequel.lit('COALESCE(satoshis, (data->>?)::bigint, 0) >= ?', 'satoshis', min_satoshis)
+          )
+        end
+        satoshis_expr = Sequel.lit('COALESCE(satoshis, (data->>?)::bigint, 0)', 'satoshis')
+        ds = ds.order(sort_order == :asc ? Sequel.asc(satoshis_expr) : Sequel.desc(satoshis_expr))
+        ds.all.map { |r| symbolise_keys(r[:data]) }
+      end
+
+      # Transitions the state of an existing output.
+      #
+      # When +new_state+ is +:pending+, sets +pending_since+, +pending_reference+,
+      # and +no_send+, and merges those values into the JSONB +data+ blob.
+      #
+      # When transitioning away from +:pending+, clears the pending metadata
+      # columns and removes the corresponding keys from the JSONB blob.
+      #
+      # @param outpoint [String] the outpoint identifier
+      # @param new_state [Symbol] +:spendable+, +:pending+, or +:spent+
+      # @param pending_reference [String, nil] caller-supplied label for a pending lock
+      # @param no_send [Boolean, nil] true if the lock belongs to a no_send transaction
+      # @raise [BSV::Wallet::WalletError] if the outpoint is not found
+      # @return [Hash] the updated output hash
+      def update_output_state(outpoint, new_state, pending_reference: nil, no_send: nil)
+        state_str = new_state.to_s
+
+        # Keep legacy spendable boolean in sync so filter_outputs and other
+        # queries that haven't migrated to the state column still work.
+        spendable_bool = new_state == :spendable
+
+        if new_state == :pending
+          updates = {
+            state: state_str,
+            spendable: spendable_bool,
+            pending_since: Sequel.lit('NOW()'),
+            pending_reference: pending_reference,
+            no_send: no_send ? true : false,
+            data: Sequel.lit(
+              "data || jsonb_build_object('state', ?, 'pending_since', NOW()::text, 'pending_reference', ?, 'no_send', ?)",
+              state_str, pending_reference, no_send ? true : false
+            )
+          }
+        else
+          updates = {
+            state: state_str,
+            spendable: spendable_bool,
+            pending_since: nil,
+            pending_reference: nil,
+            no_send: false
+          }
+          # Remove pending keys from JSONB blob, update state
+          updates[:data] = Sequel.lit(
+            "(data - 'pending_since' - 'pending_reference' - 'no_send') || jsonb_build_object('state', ?)",
+            state_str
+          )
+        end
+
+        ds = @db[:wallet_outputs].where(outpoint: outpoint)
+        rows_updated = ds.update(updates)
+        raise WalletError, "Output not found: #{outpoint}" if rows_updated.zero?
+
+        row = ds.first
+        symbolise_keys(row[:data])
+      end
+
+      # Atomically marks a set of outpoints as +:pending+.
+      #
+      # Uses +UPDATE ... WHERE state = 'spendable' ... RETURNING outpoint+ so that
+      # the check-and-set is atomic at the database level. A concurrent caller that
+      # wins the race will have already changed the state to 'pending', so the
+      # second caller's WHERE clause will not match and will return nothing. No
+      # explicit row-level locking is needed — the UPDATE itself takes the lock.
+      #
+      # Legacy rows with +state = NULL AND spendable = TRUE+ are also eligible.
+      #
+      # @param outpoints [Array<String>] outpoint identifiers to lock
+      # @param reference [String] caller-supplied pending reference
+      # @param no_send [Boolean] true if this is a no_send lock
+      # @return [Array<String>] outpoints that were actually locked
+      def lock_utxos(outpoints, reference:, no_send: false)
+        return [] if outpoints.empty?
+
+        rows = @db[:wallet_outputs]
+               .where(outpoint: outpoints)
+               .where(Sequel.lit('(state = ? OR (state IS NULL AND spendable = TRUE))', 'spendable'))
+               .returning(:outpoint)
+               .update(
+                 state: 'pending',
+                 spendable: false,
+                 pending_since: Sequel.lit('NOW()'),
+                 pending_reference: reference,
+                 no_send: no_send ? true : false,
+                 data: Sequel.lit(
+                   "data || jsonb_build_object('state', 'pending', 'pending_since', NOW()::text, " \
+                   "'pending_reference', ?, 'no_send', ?)",
+                   reference, no_send ? true : false
+                 )
+               )
+
+        rows.map { |r| r[:outpoint] }
+      end
+
+      # Releases stale pending locks back to +:spendable+.
+      #
+      # Any output in +:pending+ state whose +pending_since+ is older than
+      # +timeout+ seconds is reset to +spendable+ and its pending metadata is
+      # cleared. Outputs with +no_send = true+ are exempt and remain pending.
+      # Outputs with +pending_since = NULL+ are also skipped — they are treated
+      # as freshly locked (NULL means "just acquired but no timestamp yet").
+      #
+      # @param timeout [Integer] age in seconds before a lock is considered stale (default 300)
+      # @return [Integer] number of outputs released
+      def release_stale_pending!(timeout: 300)
+        rows = @db[:wallet_outputs]
+               .where(state: 'pending')
+               .where(Sequel.lit('no_send IS NOT TRUE'))
+               .where(Sequel.lit('pending_since IS NOT NULL'))
+               .where(Sequel.lit('pending_since < (NOW() - INTERVAL ?)', "#{timeout} seconds"))
+               .returning(:outpoint)
+               .update(
+                 state: 'spendable',
+                 spendable: true,
+                 pending_since: nil,
+                 pending_reference: nil,
+                 no_send: false,
+                 data: Sequel.lit(
+                   "(data - 'pending_since' - 'pending_reference' - 'no_send') || jsonb_build_object('state', 'spendable')"
+                 )
+               )
+
+        rows.length
+      end
+
       # --- Certificates ---
 
       def store_certificate(cert_data)
@@ -181,6 +336,18 @@ module BSV
         @db[:wallet_transactions].where(txid: txid).get(:tx_hex)
       end
 
+      # --- Settings ---
+
+      def store_setting(key, value)
+        @db[:wallet_settings]
+          .insert_conflict(target: :key, update: { value: value })
+          .insert(key: key, value: value)
+      end
+
+      def find_setting(key)
+        @db[:wallet_settings].where(key: key).get(:value)
+      end
+
       private
 
       # --- Row builders ---
@@ -195,11 +362,14 @@ module BSV
 
       def output_row(data)
         spendable = data[:spendable] != false # nil treated as spendable, like MemoryStore
+        state = data[:state]&.to_s
         {
           outpoint: data[:outpoint],
           basket: data[:basket],
           tags: Sequel.pg_array(Array(data[:tags]), :text),
           spendable: spendable,
+          state: state,
+          satoshis: data[:satoshis],
           data: Sequel.pg_jsonb(data.to_h)
         }
       end
@@ -224,7 +394,7 @@ module BSV
         ds = ds.where(outpoint: query[:outpoint]) if query[:outpoint]
         ds = ds.where(basket: query[:basket]) if query[:basket]
         ds = apply_array_filter(ds, :tags, query[:tags], query[:tag_query_mode])
-        ds = ds.where(spendable: true) unless query[:include_spent]
+        ds = ds.where(Sequel.lit('(state = ? OR (state IS NULL AND spendable = TRUE))', 'spendable')) unless query[:include_spent]
         ds
       end
 

data/lib/bsv/wallet_postgres/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletPostgres
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet-postgres
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bsv-wallet
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.4
+        version: 0.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.4
+        version: 0.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '1.0'
@@ -63,11 +63,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG-wallet-postgres.md
+- CHANGELOG.md
 - LICENSE
 - lib/bsv-wallet-postgres.rb
 - lib/bsv/wallet_postgres.rb
 - lib/bsv/wallet_postgres/migrations/001_create_wallet_tables.rb
+- lib/bsv/wallet_postgres/migrations/002_add_output_state.rb
+- lib/bsv/wallet_postgres/migrations/003_add_wallet_settings.rb
+- lib/bsv/wallet_postgres/migrations/004_add_pending_metadata.rb
 - lib/bsv/wallet_postgres/postgres_store.rb
 - lib/bsv/wallet_postgres/version.rb
 homepage: https://github.com/sgbett/bsv-ruby-sdk
@@ -76,7 +79,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/sgbett/bsv-ruby-sdk
   source_code_uri: https://github.com/sgbett/bsv-ruby-sdk
-  changelog_uri: https://github.com/sgbett/bsv-ruby-sdk/blob/master/CHANGELOG-wallet-postgres.md
+  changelog_uri: https://github.com/sgbett/bsv-ruby-sdk/blob/master/gem/bsv-wallet-postgres/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: