bsv-wallet-postgres 0.5.0 → 0.100.0

data/db/migrations/003_schema_constraints.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    extension :pg_enum
+
+    # --- New enum ---
+    # Ternary: root (identity key, no derivation), outbound (payment to
+    # others, no derivation), NULL (derived, has keys).
+    create_enum(:output_type, %w[root outbound])
+
+    # --- 1. blocks ---
+    alter_table(:blocks) do
+      add_constraint(:height_range) { height >= 0 }
+      add_constraint(:merkle_root_length) { length(merkle_root) =~ 32 }
+      add_constraint(:block_hash_length, 'block_hash IS NULL OR length(block_hash) = 32')
+    end
+
+    # --- 2. tx_proofs ---
+    alter_table(:tx_proofs) do
+      set_column_not_null :raw_tx
+      add_constraint(:wtxid_length)       { length(wtxid) =~ 32 }
+      add_constraint(:raw_tx_min_length)  { length(raw_tx) >= 20 }
+    end
+
+    # --- 3. actions ---
+    alter_table(:actions) do
+      drop_column :satoshis
+      set_column_not_null :description
+      add_constraint(:wtxid_length, 'wtxid IS NULL OR length(wtxid) = 32')
+      add_constraint(:description_length, 'length(description) BETWEEN 5 AND 50')
+      add_constraint(:nlocktime_range, 'NOT outgoing OR (nlocktime IS NOT NULL AND nlocktime >= 0)')
+      add_constraint(:wtxid_raw_tx_parity, '(wtxid IS NULL) = (raw_tx IS NULL)')
+    end
+
+    # Convert reference from text to uuid
+    run 'ALTER TABLE actions ALTER COLUMN reference SET NOT NULL'
+    run 'ALTER TABLE actions ALTER COLUMN reference TYPE uuid USING reference::uuid'
+    run "ALTER TABLE actions ALTER COLUMN reference SET DEFAULT gen_random_uuid()"
+
+    # --- 3. broadcasts ---
+    alter_table(:broadcasts) do
+      add_constraint(:block_hash_length, 'block_hash IS NULL OR length(block_hash) = 32')
+      add_constraint(:block_height_range, 'block_height IS NULL OR block_height >= 0')
+    end
+
+    # --- 4. baskets ---
+    alter_table(:baskets) do
+      drop_column :deleted_at
+      add_constraint(:name_length, 'length(name) BETWEEN 1 AND 300')
+      add_constraint(:name_not_default, "name != 'default'")
+      add_constraint(:target_count_range, 'target_count IS NULL OR target_count >= 0')
+      add_constraint(:target_value_range, 'target_value IS NULL OR target_value >= 0')
+    end
+    # Replace partial unique with plain unique
+    run 'DROP INDEX IF EXISTS baskets_name_index'
+    alter_table(:baskets) do
+      add_unique_constraint :name, name: :baskets_name_unique
+    end
+
+    # --- 5. outputs ---
+    # The immutable log. Derivation data lives here — it's a fact about the
+    # output, recorded when the key is derived. Spendable is pure membership.
+    alter_table(:outputs) do
+      set_column_not_null :locking_script
+      add_column :output_type, :output_type
+      add_constraint(:satoshis_range)          { satoshis >= 0 }
+      add_constraint(:vout_range)              { vout >= 0 }
+      add_constraint(:locking_script_min)      { length(locking_script) >= 1 }
+      # Typed outputs (root, outbound) use identity key or belong to
+      # others — no derivation fields allowed
+      add_constraint(:typed_no_prefix,   'output_type IS NULL OR derivation_prefix IS NULL')
+      add_constraint(:typed_no_suffix,   'output_type IS NULL OR derivation_suffix IS NULL')
+      add_constraint(:typed_no_sender,   'output_type IS NULL OR sender_identity_key IS NULL')
+      # Derived outputs (NULL type) must have all derivation fields
+      add_constraint(:derived_needs_prefix, 'output_type IS NOT NULL OR derivation_prefix IS NOT NULL')
+      add_constraint(:derived_needs_suffix, 'output_type IS NOT NULL OR derivation_suffix IS NOT NULL')
+      add_constraint(:derived_needs_sender, 'output_type IS NOT NULL OR sender_identity_key IS NOT NULL')
+    end
+
+    # --- 6. spendable ---
+    # Pure set membership — a row's existence IS the wallet.
+    alter_table(:spendable) do
+      set_column_not_null :action_id
+    end
+
+    # Outbound outputs are payments to others — they must never have a
+    # spendable row. Cross-table CHECK constraints aren't possible in
+    # PostgreSQL, so a trigger enforces this invariant.
+    run <<~SQL
+      CREATE FUNCTION prevent_outbound_spendable() RETURNS trigger AS $$
+      BEGIN
+        IF EXISTS (SELECT 1 FROM outputs WHERE id = NEW.output_id AND output_type = 'outbound') THEN
+          RAISE EXCEPTION 'spendable row forbidden for outbound output %', NEW.output_id
+            USING ERRCODE = 'check_violation';
+        END IF;
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql;
+    SQL
+    run <<~SQL
+      CREATE TRIGGER check_outbound_spendable
+        BEFORE INSERT ON spendable
+        FOR EACH ROW
+        EXECUTE FUNCTION prevent_outbound_spendable();
+    SQL
+
+    # --- 7. output_details ---
+    # change column stays — cosmetic flag for display, not structural
+    alter_table(:output_details) do
+      set_column_not_null :action_id
+    end
+
+    # --- 8. output_baskets ---
+    alter_table(:output_baskets) do
+      set_column_not_null :action_id
+    end
+
+    # --- 9. inputs ---
+    alter_table(:inputs) do
+      add_constraint(:vin_range)      { vin >= 0 }
+      add_constraint(:nsequence_range, 'nsequence BETWEEN 0 AND 4294967295')
+    end
+
+    # --- 10. labels ---
+    alter_table(:labels) do
+      drop_column :deleted_at
+      add_constraint(:label_length, 'length(label) BETWEEN 1 AND 300')
+    end
+    run 'DROP INDEX IF EXISTS labels_label_index'
+    alter_table(:labels) do
+      add_unique_constraint :label, name: :labels_label_unique
+    end
+
+    # --- 11. action_labels ---
+    alter_table(:action_labels) do
+      drop_column :deleted_at
+      # Replace FK without cascade with cascading FK
+      drop_foreign_key [:action_id]
+      add_foreign_key [:action_id], :actions, on_delete: :cascade
+    end
+
+    # --- 12. tags ---
+    alter_table(:tags) do
+      drop_column :deleted_at
+      add_constraint(:tag_length, 'length(tag) BETWEEN 1 AND 300')
+    end
+    run 'DROP INDEX IF EXISTS tags_tag_index'
+    alter_table(:tags) do
+      add_unique_constraint :tag, name: :tags_tag_unique
+    end
+
+    # --- 13. output_tags ---
+    alter_table(:output_tags) do
+      drop_column :deleted_at
+    end
+
+    # --- 14. certificates ---
+    alter_table(:certificates) do
+      drop_column :deleted_at
+    end
+
+    # --- 15. tx_reqs ---
+    alter_table(:tx_reqs) do
+      add_constraint(:wtxid_length) { length(wtxid) =~ 32 }
+      add_constraint(:status_values, "status IN ('unmined', 'completed', 'failed')")
+      add_constraint(:attempts_range) { attempts >= 0 }
+    end
+  end
+
+  down do
+    extension :pg_enum
+
+    # --- 15. tx_reqs ---
+    alter_table(:tx_reqs) do
+      drop_constraint :wtxid_length
+      drop_constraint :status_values
+      drop_constraint :attempts_range
+    end
+
+    # --- 14. certificates ---
+    alter_table(:certificates) do
+      add_column :deleted_at, :timestamptz
+    end
+
+    # --- 13. output_tags ---
+    alter_table(:output_tags) do
+      add_column :deleted_at, :timestamptz
+    end
+
+    # --- 12. tags ---
+    alter_table(:tags) do
+      drop_constraint :tag_length
+      drop_constraint :tags_tag_unique, type: :unique
+      add_column :deleted_at, :timestamptz
+    end
+    run "CREATE UNIQUE INDEX tags_tag_index ON tags (tag) WHERE deleted_at IS NULL"
+
+    # --- 11. action_labels ---
+    alter_table(:action_labels) do
+      drop_foreign_key [:action_id]
+      add_foreign_key [:action_id], :actions
+      add_column :deleted_at, :timestamptz
+    end
+
+    # --- 10. labels ---
+    alter_table(:labels) do
+      drop_constraint :label_length
+      drop_constraint :labels_label_unique, type: :unique
+      add_column :deleted_at, :timestamptz
+    end
+    run "CREATE UNIQUE INDEX labels_label_index ON labels (label) WHERE deleted_at IS NULL"
+
+    # --- 9. inputs ---
+    alter_table(:inputs) do
+      drop_constraint :vin_range
+      drop_constraint :nsequence_range
+    end
+
+    # --- 8. output_baskets ---
+    alter_table(:output_baskets) do
+      set_column_allow_null :action_id
+    end
+
+    # --- 7. output_details ---
+    alter_table(:output_details) do
+      set_column_allow_null :action_id
+    end
+
+    # --- 6. spendable ---
+    run 'DROP TRIGGER IF EXISTS check_outbound_spendable ON spendable'
+    run 'DROP FUNCTION IF EXISTS prevent_outbound_spendable()'
+    alter_table(:spendable) do
+      set_column_allow_null :action_id
+    end
+
+    # --- 5. outputs ---
+    alter_table(:outputs) do
+      drop_constraint :typed_no_prefix
+      drop_constraint :typed_no_suffix
+      drop_constraint :typed_no_sender
+      drop_constraint :derived_needs_prefix
+      drop_constraint :derived_needs_suffix
+      drop_constraint :derived_needs_sender
+      drop_constraint :satoshis_range
+      drop_constraint :vout_range
+      drop_constraint :locking_script_min
+      drop_column :output_type
+      set_column_allow_null :locking_script
+    end
+
+    # --- 4. baskets ---
+    alter_table(:baskets) do
+      drop_constraint :name_length
+      drop_constraint :name_not_default
+      drop_constraint :target_count_range
+      drop_constraint :target_value_range
+      drop_constraint :baskets_name_unique, type: :unique
+      add_column :deleted_at, :timestamptz
+    end
+    run "CREATE UNIQUE INDEX baskets_name_index ON baskets (name) WHERE deleted_at IS NULL"
+
+    # --- 3. broadcasts ---
+    alter_table(:broadcasts) do
+      drop_constraint :block_hash_length
+      drop_constraint :block_height_range
+    end
+
+    # --- 3. actions ---
+    run "ALTER TABLE actions ALTER COLUMN reference TYPE text USING reference::text"
+    run "ALTER TABLE actions ALTER COLUMN reference DROP NOT NULL"
+    alter_table(:actions) do
+      drop_constraint :wtxid_length
+      drop_constraint :description_length
+      drop_constraint :nlocktime_range
+      drop_constraint :wtxid_raw_tx_parity
+      set_column_allow_null :description
+      add_column :satoshis, :bigint
+    end
+
+    # --- 2. tx_proofs ---
+    alter_table(:tx_proofs) do
+      drop_constraint :wtxid_length
+      drop_constraint :raw_tx_min_length
+      set_column_allow_null :raw_tx
+    end
+
+    # --- 1. blocks ---
+    alter_table(:blocks) do
+      drop_constraint :height_range
+      drop_constraint :merkle_root_length
+      drop_constraint :block_hash_length
+    end
+
+    drop_enum(:output_type)
+  end
+end

data/db/migrations/004_drop_tx_reqs.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    drop_table(:tx_reqs)
+  end
+
+  down do
+    create_table(:tx_reqs) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :tx_proof_id, :tx_proofs, type: :bigint
+      column :wtxid, :bytea, null: false, unique: true
+      column :status, :text, null: false, default: 'unmined'
+      column :attempts, :integer, null: false, default: 0
+      column :notified, :boolean, null: false, default: false
+      column :history, :text
+      column :notify, :text
+      column :batch, :text
+      column :raw_tx, :bytea
+      column :input_beef, :bytea
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+
+      index :status
+
+      # Constraints from migration 003
+      constraint(:wtxid_length) { length(wtxid) =~ 32 }
+      constraint(:status_values, "status IN ('unmined', 'completed', 'failed')")
+      constraint(:attempts_range) { attempts >= 0 }
+    end
+  end
+end

data/lib/bsv/wallet/postgres/action.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Postgres
+      class Action < Sequel::Model
+        include DisplayTxid
+        include BSV::Wallet::Fetchable
+
+        plugin :timestamps, update_on_create: true
+
+        many_to_one  :tx_proof, class: 'BSV::Wallet::Postgres::TxProof'
+        one_to_one   :broadcast_entry, class: 'BSV::Wallet::Postgres::Broadcast', key: :action_id
+        one_to_many  :outputs, class: 'BSV::Wallet::Postgres::Output'
+        one_to_many  :inputs, class: 'BSV::Wallet::Postgres::Input'
+        many_to_many :labels, class: 'BSV::Wallet::Postgres::Label',
+                              join_table: :action_labels,
+                              left_key: :action_id, right_key: :label_id
+
+        # Derive BRC-100 status from structural state.
+        # No status column — the database structure IS the state.
+        #
+        # @return [Symbol]
+        def derived_status
+          return :unsigned   if wtxid.nil?
+          return :completed  if tx_proof_id
+          return :nosend     if values[:broadcast] == 'none'
+          return :unproven   unless outputs_dataset.empty?
+          return :failed     if broadcast_entry&.tx_status == 'REJECTED'
+          return :sending    if broadcast_entry
+          :unprocessed
+        end
+
+        # -- Fetchable contract --
+
+        def fetch_command
+          :get_tx_status
+        end
+
+        def fetch_args
+          { txid: dtxid }
+        end
+
+        def needs_fetch?
+          outgoing && !wtxid.nil? && tx_proof_id.nil?
+        end
+
+        # Create a TxProof from the network response when proof data is present.
+        # No-op when the transaction is not yet mined (no merkle_path/block_height).
+        #
+        # @param response [BSV::Network::ProtocolResponse] normalized response
+        def write!(response)
+          data = response.data
+          return unless data.is_a?(Hash) && data[:merkle_path] && data[:block_height]
+
+          proof_store = ProofStore.new
+          proof_id = proof_store.save_proof(
+            wtxid: wtxid,
+            proof: {
+              height: data[:block_height],
+              block_hash: decode_hex(data[:block_hash]),
+              merkle_path: decode_hex(data[:merkle_path]),
+              raw_tx: raw_tx
+            }
+          )
+          update(tx_proof_id: proof_id)
+        end
+
+        private
+
+        def decode_hex(hex)
+          return unless hex
+          return hex if hex.encoding == Encoding::BINARY
+
+          [hex].pack('H*')
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/postgres/action_label.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Postgres
+      class ActionLabel < Sequel::Model
+        plugin :timestamps, update_on_create: true
+
+        many_to_one :action, class: 'BSV::Wallet::Postgres::Action'
+        many_to_one :label, class: 'BSV::Wallet::Postgres::Label'
+      end
+    end
+  end
+end

data/lib/bsv/wallet/postgres/arc_adapter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Postgres
+      # Bridges the BroadcastQueue's arc_client interface (which passes raw_tx
+      # binary) with the SDK's ARC protocol (which expects Transaction objects).
+      #
+      # @example
+      #   provider = BSV::Network::Providers::GorillaPool.mainnet
+      #   adapter = ArcAdapter.new(provider)
+      #   broadcast_queue = BroadcastQueue.new(db: db, arc_client: adapter)
+      class ArcAdapter
+        def initialize(provider)
+          @provider = provider
+        end
+
+        def call(method, *args, **kwargs)
+          case method
+          when :broadcast
+            tx = BSV::Transaction::Transaction.from_binary(args.first)
+            @provider.call(:broadcast, tx)
+          when :get_tx_status
+            @provider.call(:get_tx_status, **kwargs)
+          else
+            @provider.call(method, *args, **kwargs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/postgres/basket.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Postgres
+      class Basket < Sequel::Model
+        plugin :timestamps, update_on_create: true
+
+        one_to_many :output_baskets, class: 'BSV::Wallet::Postgres::OutputBasket'
+      end
+    end
+  end
+end

data/lib/bsv/wallet/postgres/block.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Postgres
+      class Block < Sequel::Model
+        plugin :timestamps, update_on_create: true
+
+        one_to_many :tx_proofs, class: 'BSV::Wallet::Postgres::TxProof'
+      end
+    end
+  end
+end

data/lib/bsv/wallet/postgres/broadcast.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Postgres
+      class Broadcast < Sequel::Model
+        include BSV::Wallet::Pushable
+        include BSV::Wallet::Fetchable
+
+        plugin :timestamps, update_on_create: true
+
+        many_to_one :action, class: 'BSV::Wallet::Postgres::Action'
+
+        # Broadcasts with these statuses are considered terminal — no further polling.
+        TERMINAL_STATUSES = %w[
+          SEEN_ON_NETWORK MINED IMMUTABLE
+          REJECTED DOUBLE_SPEND_ATTEMPTED
+        ].freeze
+
+        # Minimum age (seconds) before a broadcast is eligible for status polling.
+        FETCH_STALENESS = 30
+
+        # --- Pushable contract ---
+
+        def push_command
+          :broadcast
+        end
+
+        def push_payload
+          action.raw_tx
+        end
+
+        def needs_push?
+          broadcast_at.nil? && action&.raw_tx
+        end
+
+        # --- Fetchable contract ---
+
+        def fetch_command
+          :get_tx_status
+        end
+
+        def fetch_args
+          { txid: action.dtxid }
+        end
+
+        def needs_fetch?
+          return false unless broadcast_at
+          return false if TERMINAL_STATUSES.include?(tx_status)
+
+          broadcast_at < Time.now - FETCH_STALENESS
+        end
+
+        # --- Shared write ---
+
+        # Update columns from a normalized Services response.
+        #
+        # @param response [BSV::Network::ProtocolResponse] normalized response
+        def write!(response)
+          data = response.data
+          return unless data.is_a?(Hash)
+
+          fields = {}
+          fields[:broadcast_at] = Time.now if broadcast_at.nil?
+          fields[:tx_status] = data[:tx_status] if data[:tx_status]
+          fields[:arc_status] = data[:status] if data[:status]
+          fields[:block_hash] = decode_hex(data[:block_hash]) if data[:block_hash]
+          fields[:block_height] = data[:block_height] if data[:block_height]
+          fields[:merkle_path] = decode_hex(data[:merkle_path]) if data[:merkle_path]
+          fields[:extra_info] = data[:extra_info] if data[:extra_info]
+          fields[:competing_txs] = Sequel.pg_array(data[:competing_txs]) if data[:competing_txs]
+
+          update(fields) unless fields.empty?
+        end
+
+        private
+
+        def decode_hex(value)
+          return unless value
+          return Sequel.blob(value) if value.encoding == Encoding::BINARY
+
+          Sequel.blob([value].pack('H*'))
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/postgres/broadcast_callback.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rack'
+
+module BSV
+  module Wallet
+    module Postgres
+      # Rack app that receives ARC TransactionStatus webhook POSTs
+      # and delegates to a BroadcastQueue instance.
+      #
+      # Mount however the host application prefers:
+      #   - Standalone: rackup with config.ru
+      #   - Rails: mount BroadcastCallback.new(broadcast_queue:) => '/arc/callback'
+      class BroadcastCallback
+        def initialize(broadcast_queue:)
+          @broadcast_queue = broadcast_queue
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          body = JSON.parse(request.body.read, symbolize_names: true)
+          event = decode_event(body)
+          @broadcast_queue.handle_event(event)
+          [200, { 'content-type' => 'text/plain' }, ['OK']]
+        rescue JSON::ParserError
+          [400, { 'content-type' => 'text/plain' }, ['Bad Request']]
+        end
+
+        private
+
+        def decode_event(body)
+          BSV::Primitives::Hex.validate_dtxid_hex!(body[:txid], name: 'ARC callback txid') if body[:txid]
+          {
+            wtxid:         decode_hex(body[:txid])&.reverse,
+            tx_status:     body[:txStatus],
+            status:        body[:status],
+            block_hash:    decode_hex(body[:blockHash]),
+            block_height:  body[:blockHeight],
+            merkle_path:   decode_hex(body[:merklePath]),
+            extra_info:    body[:extraInfo],
+            competing_txs: body[:competingTxs]
+          }
+        end
+
+        def decode_hex(hex)
+          return unless hex
+
+          [hex].pack('H*')
+        end
+      end
+    end
+  end
+end