bsv-wallet-postgres 0.6.0 → 0.100.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c61ec2b4c48854fcba55eeb47bb1d7b3e87129fbf01769e07fc6c30661d1a26
-  data.tar.gz: 58f953f0a5d5fb10fb20259d821dc604ba842f8210f53d6f55be12e760ed927c
+  metadata.gz: 828e610f2e6640f09db4de4dddad8e86fa25b6416610b57c026852c73abdb784
+  data.tar.gz: 3d89fc8d066a3c4363a295942e1644efaa1e8535971ab6a4cbe81f5a01a282ae
 SHA512:
-  metadata.gz: 5b51ceb9562b914012b2a86ee1c236501f9f714583a55d46a977e6418f0cf490497d7a42349210a0e0ee1436179617d45ded1afca815f0770d563aad8bf4051a
-  data.tar.gz: 6f219ead476cf621c654e9692f955962f96f55d02b900bb03f2adfe1549b331abd714036e4af7ef32f1c322e72c452a64ebebdcda46cedc9fc239e601cc0bf5f
+  metadata.gz: 98e82a0962d6005cb7c76eee3bee04a0a8a52e834462056a34ce417edb5b1c5bc46eef792c8ab32e33e50e02d454b56e5dfd72017bd42a86aa248146cf767732
+  data.tar.gz: 6598af72c9d416a533e4939a2a1746034d006b77f86395bdebd4cd4863bd34ae68e2548c88ace670adecddce2fd5f6ad7fef4065b14c1512a24d29b95ae9d2c7

data/CHANGELOG.md

@@ -1,133 +1,27 @@
-# Changelog — bsv-wallet-postgres
+# Changelog
 
-All notable changes to the `bsv-wallet-postgres` gem are documented here.
+## [0.100.0] - 2026-05-13
 
-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.6.0 — 2026-04-21
-
-### Added
-- `update_output_basket` implementation on `PostgresStore`, matching the new Store interface method
-
-### Changed
-- Updated for bsv-wallet 0.10.0 namespace changes (`Interface`, `Client`, `Store`)
-
-## 0.5.0 — 2026-04-16
-
-### Changed — **Breaking**
-
-- `SolidQueueAdapter` now sets the wallet action status to `'unproven'` instead of `'completed'` on successful broadcast. Aligns with the status taxonomy change in bsv-wallet 0.9.0 (HLR #455). The `wallet_broadcast_jobs` row status is unchanged (job queue lifecycle is a separate domain).
-
-### Added
-
-- `BroadcastQueue#broadcast_enabled?` interface method; `SolidQueueAdapter` returns `true` (broadcaster required at construction time). Enables `WalletClient#broadcast_enabled?` to detect a queue-embedded broadcaster.
-
-### Changed
-
-- Minimum `bsv-wallet` version raised from `>= 0.6.0` to `>= 0.9.0`. Required for the new status taxonomy and `broadcast_enabled?` interface.
-
-## 0.4.0 — 2026-04-12
-
-### Added
-- `BSV::Wallet::SolidQueueAdapter` — PostgreSQL-backed async broadcast queue implementing the `BroadcastQueue` interface
-- Migration 006: `wallet_broadcast_jobs` table with `FOR UPDATE SKIP LOCKED` polling support
-- Background worker thread broadcasts transactions and promotes/rolls back wallet state
-- Recovery on restart via stale `locked_at` detection
-- Idempotent enqueue on duplicate txid (crash recovery)
-- `MAX_ATTEMPTS` enforcement (5) prevents infinite retry loops
-- Guard refuses MemoryStore attachment
-
-### Fixed
-- Migration timestamps use `timestamptz` (matching migration 004 pattern)
-- `start()` check-and-set is atomic under mutex (prevents TOCTOU double-spawn)
-- Deserialization failures mark job as failed immediately (no tight retry loop)
-
-## 0.3.1 — 2026-04-12
-
-### Fixed
-- `update_action_status` now scopes to a single row by primary key, preventing unintended multi-row updates when duplicate txids exist
-- Added migration 005: unique index on `wallet_actions.txid` enforcing one action per transaction
-
-## 0.3.0 — 2026-04-12
+First release of the PostgreSQL adapter for the Ruby BRC-100 wallet.
 
 ### Added
-- `update_action_status` and `delete_action` implementations for PostgresStore,
-  matching the new StorageAdapter contract introduced in bsv-wallet 0.6.0 (#370)
-
-## 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
+- **Schema** — actions, outputs, inputs, spendable, baskets, labels, tags, certificates, tx_proofs, blocks, broadcasts
+- **Store** — full BRC-100 action lifecycle: create, sign, promote, abort, reap, list, query
+- **ProofStore** — merkle proof persistence with block normalization
+- **UTXOPool** — UTXO selection with sizing strategy and limp mode
+- **BroadcastQueue** — broadcast lifecycle management
+- **Pushable/Fetchable** — Broadcast and Action adopt entity-driven network interaction
+- **Migrations** — sequential schema migrations with constraint enforcement
+- **Database trigger** — prevents outbound outputs from entering the spendable set
 
 ### Changed
+- **blocks table** — normalized from tx_proofs; stores block headers independently
+- **tx_reqs removed** — replaced by structural queries via Fetchable pattern
 
-- Directory restructure — source moved to `gem/bsv-wallet-postgres/`
-
-## 0.1.0 — 2026-04-09
-
-Initial release of `bsv-wallet-postgres`, a PostgreSQL-backed
-`BSV::Wallet::StorageAdapter` implementation. Unblocks production
-deployments of `bsv-wallet` where state has to survive container
-restarts, and makes multi-instance wallet services possible for the
-first time.
+## [0.1.0] - 2026-05-01
 
 ### Added
 
-- **`BSV::Wallet::PostgresStore`** — full
-  `StorageAdapter` implementation over Sequel + Postgres. Passes the
-  same shared conformance suite that MemoryStore and FileStore pass
-  (53 examples), plus 10 postgres-specific specs covering upsert
-  semantics, GIN tag queries, JSONB attribute containment, concurrent
-  inserts, and migration idempotency.
-
-- **Shipped Sequel migration** at
-  `lib/bsv/wallet_postgres/migrations/001_create_wallet_tables.rb`.
-  Five tables (wallet_outputs, wallet_actions, wallet_certificates,
-  wallet_proofs, wallet_transactions) with JSONB data columns,
-  dedicated indexed columns for filter paths, and GIN indexes on the
-  `tags` / `labels` arrays.
-
-- **`PostgresStore.migrate!(db)`** convenience
-  wrapper over `Sequel::Migrator.run` so consumers can apply the
-  shipped schema with a single call. Operators who prefer their own
-  migration framework can copy the migration file instead.
-
-- **Docs** at `docs/guides/wallet-postgres.md` with
-  a 30-second quickstart, schema overview, and production
-  considerations (pool sizing, multi-instance, backups,
-  thread-safety).
-
-### Infrastructure
-
-- **CI postgres service**. The GitHub Actions test job now runs a
-  Postgres 16 container and exposes `DATABASE_URL` to rspec, so the
-  `:postgres`-tagged specs run against a live database on every
-  Ruby matrix row (2.7 → 3.4). Local developers without Postgres
-  still get a green suite — those specs skip gracefully.
-
-### Dependencies
-
-- `bsv-wallet-postgres` runtime: `bsv-wallet >= 0.3.4, < 1.0`,
-  `sequel ~> 5`, `pg ~> 1`. The wallet floor matches the pinning style
-  `bsv-wallet` uses for its `bsv-sdk` dependency so security releases
-  propagate.
+- Initial 17-table PostgreSQL schema migration
+- Sequel models for all wallet tables
+- Connection management module

data/LICENSE

@@ -1,86 +1,29 @@
-Open BSV License Version 5 – granted by BSV Association, Grafenauweg 6, 6300
-Zug, Switzerland (CHE-427.008.338) ("Licensor"), to you as a user (henceforth
-"You", "User" or "Licensee").
+Open BSV License
 
-For the purposes of this license, the definitions below have the following
-meanings:
+Copyright (c) 2026 Simon Bettison
 
-"Bitcoin Protocol" means the protocol implementation, cryptographic rules,
-network protocols, and consensus mechanisms in the Bitcoin White Paper as
-described here https://protocol.bsvblockchain.org.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-"Bitcoin White Paper" means the paper entitled 'Bitcoin: A Peer-to-Peer
-Electronic Cash System' published by 'Satoshi Nakamoto' in October 2008.
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
 
-"BSV Blockchains" means:
-  (a) the Bitcoin blockchain containing block height #556767 with the hash
-      "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
-      that contains the longest honest persistent chain of blocks which has been
-      produced in a manner which is consistent with the rules set forth in the
-      Network Access Rules; and
-  (b) the test blockchains that contain the longest honest persistent chains of
-      blocks which has been produced in a manner which is consistent with the
-      rules set forth in the Network Access Rules.
-
-"Network Access Rules" or "Rules" means the set of rules regulating the
-relationship between BSV Association and the nodes on BSV based on the Bitcoin
-Protocol rules and those set out in the Bitcoin White Paper, and available here
-https://bsvblockchain.org/network-access-rules.
-
-"Software" means the software the subject of this licence, including any/all
-intellectual property rights therein and associated documentation files.
-
-BSV Association grants permission, free of charge and on a non-exclusive and
-revocable basis, to any person obtaining a copy of the Software to deal in the
-Software without restriction, including without limitation the rights to use,
-copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
-Software, and to permit persons to whom the Software is furnished to do so,
-subject to and conditioned upon the following conditions:
-
-1 - The text "© BSV Association," and this license shall be included in all
-copies or substantial portions of the Software.
-2 - The Software, and any software that is derived from the Software or parts
-thereof, must only be used on the BSV Blockchains.
-
-For the avoidance of doubt, this license is granted subject to and conditioned
-upon your compliance with these terms only. In the event of non-compliance, the
-license shall extinguish and you can be enjoined from violating BSV's
-intellectual property rights (incl. damages and similar related claims).
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES REGARDING ENTITLEMENT,
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
-EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS THEREOF BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
-DEALINGS IN THE SOFTWARE.
-
-
-Version 0.1.1 of the Bitcoin SV software, and prior versions of software upon
-which it was based, were licensed under the MIT License, which is included below.
-
-The MIT License (MIT)
-
-Copyright (c) 2009-2010 Satoshi Nakamoto
-Copyright (c) 2009-2015 Bitcoin Developers
-Copyright (c) 2009-2017 The Bitcoin Core developers
-Copyright (c) 2017 The Bitcoin ABC developers
-Copyright (c) 2018 Bitcoin Association for BSV
-Copyright (c) 2023 BSV Association
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
-the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+2. The Software, and any software that is derived from the Software or parts
+   thereof, can only be used on the Bitcoin SV blockchains. The Bitcoin SV
+   blockchains are defined, for purposes of this license, as the Bitcoin
+   blockchain containing block combinator
+   000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b and the
+   test combinator
+   00000000a6e140e27e4eb65e3cb4e4e07b1a0e3964b396c97a4b36e4ac06eb54.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/db/migrations/001_create_schema.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    extension :pg_enum
+
+    # Enum: broadcast intent for actions
+    create_enum(:broadcast_intent, %w[delayed inline none])
+
+    # 1. blocks — known block headers (chain tracker's local view)
+    create_table(:blocks) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :height, :integer, null: false, unique: true
+      column :merkle_root, :bytea, null: false
+      column :block_hash, :bytea
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+    end
+
+    # 2. tx_proofs — merkle inclusion proofs (settlement evidence)
+    create_table(:tx_proofs) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :wtxid, :bytea, null: false, unique: true
+      foreign_key :block_id, :blocks, type: :bigint
+      column :block_index, :integer
+      column :merkle_path, :bytea
+      column :raw_tx, :bytea
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+    end
+
+    # 2. actions — transaction lifecycle
+    create_table(:actions) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :tx_proof_id, :tx_proofs, type: :bigint
+      column :wtxid, :bytea
+      column :reference, :text, unique: true, default: Sequel.function(:gen_random_uuid)
+      column :outgoing, :boolean, null: false, default: true
+      column :satoshis, :bigint
+      column :description, :text
+      column :version, :integer
+      column :nlocktime, :bigint
+      column :broadcast, :broadcast_intent, null: false, default: 'delayed'
+      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 :wtxid, unique: true, where: Sequel.lit('wtxid IS NOT NULL')
+      index :broadcast
+    end
+
+    # 3. broadcasts — ARC lifecycle
+    create_table(:broadcasts) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :action_id, :actions, type: :bigint, null: false, unique: true
+      column :broadcast_at, :timestamptz
+      column :tx_status, :text
+      column :arc_status, :integer
+      column :block_hash, :bytea
+      column :block_height, :integer
+      column :merkle_path, :bytea
+      column :extra_info, :text
+      column :competing_txs, 'text[]'
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+    end
+
+    # 4. baskets — output grouping with replenishment policy
+    create_table(:baskets) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :name, :text, null: false
+      column :target_count, :integer
+      column :target_value, :integer
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :deleted_at, :timestamptz
+
+      index :name, unique: true, where: Sequel.lit('deleted_at IS NULL')
+    end
+
+    # 5. outputs — immutable append-only log
+    create_table(:outputs) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :action_id, :actions, type: :bigint, null: false
+      column :satoshis, :bigint, null: false
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :locking_script, :bytea
+      column :vout, :integer, null: false
+      column :sender_identity_key, :text
+      column :derivation_prefix, :text
+      column :derivation_suffix, :text
+
+      unique %i[action_id vout]
+    end
+
+    # 6. spendable — the UTXO set (~28 bytes/row)
+    create_table(:spendable) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :output_id, :outputs, type: :bigint, null: false, unique: true
+    end
+
+    # 7. output_details — display and application metadata
+    create_table(:output_details) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :output_id, :outputs, type: :bigint, null: false, unique: true
+      column :change, :boolean, null: false, default: false
+      column :type, :text
+      column :purpose, :text
+      column :provided_by, :text
+      column :description, :text
+      column :custom_instructions, :text
+      column :script_length, :integer
+      column :script_offset, :integer
+    end
+
+    # 8. output_baskets — basket membership
+    create_table(:output_baskets) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :output_id, :outputs, type: :bigint, null: false, unique: true
+      foreign_key :basket_id, :baskets, type: :bigint, null: false
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+
+      index :basket_id
+    end
+
+    # 9. inputs — structural lock mechanism
+    create_table(:inputs) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :action_id, :actions, type: :bigint, null: false, on_delete: :cascade
+      foreign_key :output_id, :outputs, type: :bigint, null: false
+      column :vin, :integer, null: false
+      column :nsequence, :bigint, null: false, default: 4_294_967_295
+      column :description, :text
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+
+      unique :output_id
+      unique %i[action_id vin]
+    end
+
+    # 10. labels — label definitions
+    create_table(:labels) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :label, :text, null: false
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :deleted_at, :timestamptz
+
+      index :label, unique: true, where: Sequel.lit('deleted_at IS NULL')
+    end
+
+    # 11. action_labels — join table
+    create_table(:action_labels) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :action_id, :actions, type: :bigint, null: false
+      foreign_key :label_id, :labels, type: :bigint, null: false
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :deleted_at, :timestamptz
+
+      unique %i[action_id label_id]
+      index :label_id
+    end
+
+    # 12. tags — tag definitions
+    create_table(:tags) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :tag, :text, null: false
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :deleted_at, :timestamptz
+
+      index :tag, unique: true, where: Sequel.lit('deleted_at IS NULL')
+    end
+
+    # 13. output_tags — join table
+    create_table(:output_tags) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :output_id, :outputs, type: :bigint, null: false
+      foreign_key :tag_id, :tags, type: :bigint, null: false
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :deleted_at, :timestamptz
+
+      unique %i[output_id tag_id]
+      index :tag_id
+    end
+
+    # 14. certificates — identity certificates (BRC-52)
+    create_table(:certificates) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :type, :text, null: false
+      column :subject, :text
+      column :serial_number, :text, null: false
+      column :certifier, :text, null: false
+      column :verifier, :text
+      column :revocation_outpoint, :text
+      column :signature, :text
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :deleted_at, :timestamptz
+
+      unique %i[type serial_number certifier]
+      index :certifier
+      index :subject
+    end
+
+    # 15. certificate_fields — per-field encryption for selective revelation
+    create_table(:certificate_fields) do
+      column :id, :bigint, primary_key: true, identity: :always
+      foreign_key :certificate_id, :certificates, type: :bigint, null: false, on_delete: :cascade
+      column :name, :text, null: false
+      column :value, :text
+      column :master_key, :text
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+
+      unique %i[certificate_id name]
+    end
+
+    # 16. tx_reqs — proof-harvesting work queue
+    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
+    end
+
+    # 17. settings — key-value wallet configuration
+    create_table(:settings) do
+      column :id, :bigint, primary_key: true, identity: :always
+      column :key, :text, null: false, unique: true
+      column :value, :text
+      column :created_at, :timestamptz, null: false, default: Sequel.function(:now)
+      column :updated_at, :timestamptz, null: false, default: Sequel.function(:now)
+    end
+  end
+
+  down do
+    drop_table :settings, :tx_reqs, :certificate_fields, :certificates,
+               :output_tags, :tags, :action_labels, :labels, :inputs,
+               :output_baskets, :output_details, :spendable, :outputs,
+               :baskets, :broadcasts, :actions, :tx_proofs, :blocks
+
+    extension :pg_enum
+    drop_enum(:broadcast_intent)
+  end
+end

data/db/migrations/002_action_id_cascade.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    # Add action_id with ON DELETE CASCADE to relationship tables.
+    # Denormalized (derivable via output_id -> outputs.action_id) but
+    # justified: set once at creation, never changes, enables cascade
+    # cleanup — deleting an action automatically removes its spendable
+    # entries, basket memberships, and output details.
+    add_column :spendable, :action_id, :bigint
+    run <<~SQL
+      ALTER TABLE spendable
+        ADD CONSTRAINT spendable_action_id_fkey
+        FOREIGN KEY (action_id) REFERENCES actions (id) ON DELETE CASCADE
+    SQL
+
+    add_column :output_baskets, :action_id, :bigint
+    run <<~SQL
+      ALTER TABLE output_baskets
+        ADD CONSTRAINT output_baskets_action_id_fkey
+        FOREIGN KEY (action_id) REFERENCES actions (id) ON DELETE CASCADE
+    SQL
+
+    add_column :output_details, :action_id, :bigint
+    run <<~SQL
+      ALTER TABLE output_details
+        ADD CONSTRAINT output_details_action_id_fkey
+        FOREIGN KEY (action_id) REFERENCES actions (id) ON DELETE CASCADE
+    SQL
+
+    # Change outputs.action_id FK to ON DELETE SET NULL and make nullable.
+    # Outputs are immutable log entries — when an action is deleted (abort,
+    # reaper), the output rows survive as orphans with NULL action_id.
+    # They have no spendable entry (cascade-deleted), no basket, and are
+    # invisible to the wallet.
+    run <<~SQL
+      ALTER TABLE outputs
+        DROP CONSTRAINT IF EXISTS outputs_action_id_fkey,
+        ALTER COLUMN action_id DROP NOT NULL,
+        ADD CONSTRAINT outputs_action_id_fkey
+          FOREIGN KEY (action_id) REFERENCES actions (id) ON DELETE SET NULL
+    SQL
+  end
+
+  down do
+    run <<~SQL
+      ALTER TABLE outputs
+        DROP CONSTRAINT IF EXISTS outputs_action_id_fkey,
+        ALTER COLUMN action_id SET NOT NULL,
+        ADD CONSTRAINT outputs_action_id_fkey
+          FOREIGN KEY (action_id) REFERENCES actions (id)
+    SQL
+    alter_table(:spendable) do
+      drop_constraint :spendable_action_id_fkey
+      drop_column :action_id
+    end
+    alter_table(:output_baskets) do
+      drop_constraint :output_baskets_action_id_fkey
+      drop_column :action_id
+    end
+    alter_table(:output_details) do
+      drop_constraint :output_details_action_id_fkey
+      drop_column :action_id
+    end
+  end
+end