bsv-wallet-postgres 0.5.0 → 0.100.0

data/lib/bsv/wallet/postgres.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # PostgreSQL adapter for bsv-wallet.
+    #
+    # Call {.connect} before using any models. Loads the pg_enum and pg_array
+    # Sequel extensions and sets Sequel::Model.db for all models in this namespace.
+    module Postgres
+      autoload :VERSION,          'bsv/wallet/postgres/version'
+
+      # Component services (Layer 2a)
+      autoload :Store,             'bsv/wallet/postgres/store'
+      autoload :UTXOPool,          'bsv/wallet/postgres/utxo_pool'
+      autoload :BroadcastQueue,    'bsv/wallet/postgres/broadcast_queue'
+      autoload :BroadcastCallback, 'bsv/wallet/postgres/broadcast_callback'
+      autoload :ProofStore,        'bsv/wallet/postgres/proof_store'
+      autoload :ArcAdapter,        'bsv/wallet/postgres/arc_adapter'
+
+      # Shared concerns
+      require_relative 'postgres/display_txid'
+
+      # Models (Layer 2b — atomic services)
+      autoload :Block,            'bsv/wallet/postgres/block'
+      autoload :TxProof,          'bsv/wallet/postgres/tx_proof'
+      autoload :Action,           'bsv/wallet/postgres/action'
+      autoload :Broadcast,        'bsv/wallet/postgres/broadcast'
+      autoload :Basket,           'bsv/wallet/postgres/basket'
+      autoload :Output,           'bsv/wallet/postgres/output'
+      autoload :Spendable,        'bsv/wallet/postgres/spendable'
+      autoload :OutputDetail,     'bsv/wallet/postgres/output_detail'
+      autoload :OutputBasket,     'bsv/wallet/postgres/output_basket'
+      autoload :Input,            'bsv/wallet/postgres/input'
+      autoload :Label,            'bsv/wallet/postgres/label'
+      autoload :ActionLabel,      'bsv/wallet/postgres/action_label'
+      autoload :Tag,              'bsv/wallet/postgres/tag'
+      autoload :OutputTag,        'bsv/wallet/postgres/output_tag'
+      autoload :Certificate,      'bsv/wallet/postgres/certificate'
+      autoload :CertificateField, 'bsv/wallet/postgres/certificate_field'
+
+      autoload :Setting,          'bsv/wallet/postgres/setting'
+
+      class << self
+        # @return [Sequel::Database, nil] the connected database
+        attr_reader :db
+
+        # Establish a database connection for all models.
+        #
+        # @param url_or_db [String, Sequel::Database] connection URL or existing database
+        # @return [Sequel::Database]
+        def connect(url_or_db)
+          @db = url_or_db.is_a?(Sequel::Database) ? url_or_db : Sequel.connect(url_or_db)
+          @db.extension :pg_enum
+          @db.extension :pg_array
+          @db.extension :pg_json
+          Sequel::Model.db = @db
+          @db
+        end
+
+        # Disconnect and clear the database reference.
+        def disconnect
+          @db&.disconnect
+          @db = nil
+        end
+
+        # Run pending migrations against the connected database.
+        #
+        # @param target [Integer, nil] optional target migration version
+        def migrate!(target: nil)
+          Sequel.extension :migration
+          migrations_path = File.expand_path('../../db/migrations', __dir__)
+          Sequel::Migrator.run(@db, migrations_path, target: target)
+        end
+      end
+    end
+  end
+end

data/lib/bsv-wallet-postgres.rb

@@ -2,4 +2,4 @@
 
 require 'sequel'
 require 'bsv-wallet'
-require_relative 'bsv/wallet_postgres'
+require_relative 'bsv/wallet/postgres'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet-postgres
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.100.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -15,74 +15,88 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: pg
+  name: sequel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
-  name: sequel
+  name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
-description: Persistent Sequel/Postgres-backed BSV::Wallet::StorageAdapter implementation
-  for production BSV wallet deployments.
+        version: '0'
+description: Sequel models, migrations, and concrete Store/BroadcastQueue/ProofStore
+  implementations for the bsv-wallet gem, backed by PostgreSQL.
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
+- db/migrations/001_create_schema.rb
+- db/migrations/002_action_id_cascade.rb
+- db/migrations/003_schema_constraints.rb
+- db/migrations/004_drop_tx_reqs.rb
 - 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/migrations/005_add_txid_unique_index.rb
-- lib/bsv/wallet_postgres/migrations/006_create_broadcast_jobs.rb
-- lib/bsv/wallet_postgres/postgres_store.rb
-- lib/bsv/wallet_postgres/solid_queue_adapter.rb
-- lib/bsv/wallet_postgres/version.rb
-homepage: https://github.com/sgbett/bsv-ruby-sdk
+- lib/bsv/wallet/postgres.rb
+- lib/bsv/wallet/postgres/action.rb
+- lib/bsv/wallet/postgres/action_label.rb
+- lib/bsv/wallet/postgres/arc_adapter.rb
+- lib/bsv/wallet/postgres/basket.rb
+- lib/bsv/wallet/postgres/block.rb
+- lib/bsv/wallet/postgres/broadcast.rb
+- lib/bsv/wallet/postgres/broadcast_callback.rb
+- lib/bsv/wallet/postgres/broadcast_queue.rb
+- lib/bsv/wallet/postgres/certificate.rb
+- lib/bsv/wallet/postgres/certificate_field.rb
+- lib/bsv/wallet/postgres/display_txid.rb
+- lib/bsv/wallet/postgres/input.rb
+- lib/bsv/wallet/postgres/label.rb
+- lib/bsv/wallet/postgres/output.rb
+- lib/bsv/wallet/postgres/output_basket.rb
+- lib/bsv/wallet/postgres/output_detail.rb
+- lib/bsv/wallet/postgres/output_tag.rb
+- lib/bsv/wallet/postgres/proof_store.rb
+- lib/bsv/wallet/postgres/setting.rb
+- lib/bsv/wallet/postgres/spendable.rb
+- lib/bsv/wallet/postgres/store.rb
+- lib/bsv/wallet/postgres/tag.rb
+- lib/bsv/wallet/postgres/tx_proof.rb
+- lib/bsv/wallet/postgres/utxo_pool.rb
+- lib/bsv/wallet/postgres/version.rb
+homepage: https://github.com/sgbett/bsv-wallet
 licenses:
 - LicenseRef-OpenBSV
 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/gem/bsv-wallet-postgres/CHANGELOG.md
+  homepage_uri: https://github.com/sgbett/bsv-wallet
+  source_code_uri: https://github.com/sgbett/bsv-wallet
+  changelog_uri: https://github.com/sgbett/bsv-wallet/blob/master/gem/bsv-wallet-postgres/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -91,7 +105,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -100,5 +114,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: PostgreSQL storage adapter for bsv-wallet
+summary: PostgreSQL adapter for bsv-wallet
 test_files: []

data/lib/bsv/wallet_postgres/migrations/001_create_wallet_tables.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-# Initial wallet schema for BSV::Wallet::PostgresStore.
-#
-# Five tables, all indexed for the query patterns the StorageAdapter
-# interface exposes. JSONB blobs hold the full hash the SDK stored so
-# adding fields to bsv-wallet's output/action/certificate records does
-# not require a schema change — only the fields we actively filter on
-# get dedicated indexed columns.
-Sequel.migration do
-  change do
-    create_table(:wallet_outputs) do
-      primary_key :id
-      String :outpoint, null: false, unique: true
-      String :basket
-      column :tags, 'text[]'
-      TrueClass :spendable, null: false, default: true
-      jsonb :data, null: false
-      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
-      index %i[basket spendable]
-      index :tags, type: :gin
-    end
-
-    create_table(:wallet_actions) do
-      primary_key :id
-      String :txid, null: false
-      column :labels, 'text[]'
-      jsonb :data, null: false
-      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
-      index :labels, type: :gin
-    end
-
-    create_table(:wallet_certificates) do
-      primary_key :id
-      String :type, null: false
-      String :serial_number, null: false
-      String :certifier, null: false
-      String :subject
-      jsonb :data, null: false
-      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
-      unique %i[type serial_number certifier], name: :wallet_certificates_natural_key
-      index :certifier
-      index :subject
-    end
-
-    create_table(:wallet_proofs) do
-      String :txid, primary_key: true
-      String :bump_hex, text: true, null: false
-      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
-    end
-
-    create_table(:wallet_transactions) do
-      String :txid, primary_key: true
-      String :tx_hex, text: true, null: false
-      DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
-    end
-  end
-end

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

@@ -1,33 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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/migrations/005_add_txid_unique_index.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-# Add a unique index on wallet_actions.txid.
-#
-# Within a single wallet there should be at most one action per transaction.
-# Without this constraint, concurrent inserts or retries could create duplicate
-# rows sharing the same txid, causing +update_action_status+ to update multiple
-# rows unintentionally.
-#
-# The index also accelerates the +where(txid:)+ lookups performed by
-# +update_action_status+ and +delete_action+.
-#
-# === Backward compatibility
-#
-# The migration will fail if duplicate txids already exist in the table. Clean
-# up any duplicates before running this migration:
-#
-#   DELETE FROM wallet_actions a
-#   USING wallet_actions b
-#   WHERE a.id > b.id AND a.txid = b.txid;
-Sequel.migration do
-  change do
-    alter_table(:wallet_actions) do
-      add_index :txid, unique: true, name: :wallet_actions_txid_unique
-    end
-  end
-end

data/lib/bsv/wallet_postgres/migrations/006_create_broadcast_jobs.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-# Broadcast job queue table for the SolidQueueAdapter.
-#
-# Tracks outbound transactions that need to be broadcast to the network,
-# with state machine, retry counters, and advisory locking support so that
-# multiple worker processes can poll the queue without double-processing.
-#
-# === Columns
-#
-# * +txid+              — TEXT NOT NULL UNIQUE. Prevents duplicate queue entries
-#                         for the same transaction.
-#
-# * +status+            — TEXT NOT NULL DEFAULT 'unsent'. State machine values:
-#                         'unsent', 'sending', 'completed', 'failed'.
-#
-# * +beef_hex+          — TEXT NOT NULL. Serialised BEEF payload to broadcast.
-#
-# * +input_outpoints+   — text[], nullable. Outpoints consumed by the tx, used
-#                         to release UTXOs on success or rollback on failure.
-#
-# * +change_outpoints+  — text[], nullable. Change outpoints created by the tx,
-#                         used to mark outputs spendable after confirmation.
-#
-# * +fund_ref+          — TEXT, nullable. Caller-supplied funding reference for
-#                         observability and reconciliation.
-#
-# * +attempts+          — INTEGER NOT NULL DEFAULT 0. Incremented on each
-#                         broadcast attempt; gates retry logic.
-#
-# * +last_error+        — TEXT, nullable. Message from the last failed attempt.
-#
-# * +locked_at+         — TIMESTAMPTZ, nullable. Set when a worker claims the
-#                         job; cleared on completion or stale-lock recovery.
-#
-# * +created_at+        — TIMESTAMPTZ NOT NULL DEFAULT NOW().
-#
-# * +updated_at+        — TIMESTAMPTZ NOT NULL DEFAULT NOW().
-#
-# === Index
-#
-# A composite index on +(status, locked_at)+ (named +broadcast_jobs_poll_idx+)
-# supports the hot-path poll query:
-#
-#   WHERE status = 'unsent'
-#      OR (status = 'sending' AND locked_at < NOW() - interval '300 seconds'
-#          AND attempts < 5)
-#   ORDER BY created_at
-#   FOR UPDATE SKIP LOCKED
-Sequel.migration do
-  change do
-    create_table(:wallet_broadcast_jobs) do
-      primary_key :id, type: :Bignum
-      String   :txid,             null: false, unique: true
-      String   :status,           null: false, default: 'unsent'
-      String   :beef_hex,         text: true, null: false
-      column   :input_outpoints,  'text[]'
-      column   :change_outpoints, 'text[]'
-      String   :fund_ref
-      Integer  :attempts,         null: false, default: 0
-      String   :last_error,       text: true
-      column :locked_at,   :timestamptz
-      column :created_at,  :timestamptz, null: false, default: Sequel::CURRENT_TIMESTAMP
-      column :updated_at,  :timestamptz, null: false, default: Sequel::CURRENT_TIMESTAMP
-      index %i[status locked_at], name: :broadcast_jobs_poll_idx
-    end
-  end
-end