db: derive IsUsed from utxos table on SQL (ADR 0011)

The earlier draft of this commit added a `used BOOL` column to the
`addresses` table plus a monotonic-clear trigger. Review re-examined
the schema after PR #1232 + ADR 0006 landed: the `transactions`
table soft-deletes via `tx_status` and the `utxos` table holds its
references via ON DELETE RESTRICT. Reorged transactions and their
utxos stay in the database; only an explicit pruning operation
removes them.

Therefore, on SQL backends, "is this address ever used?" can be
answered monotonically with

    EXISTS(SELECT 1 FROM utxos WHERE address_id = ?)

without persisting a separate column.

This commit:

  * Adds ADR 0011 capturing the decision and the asymmetric backend
    implementation (SQL derived; kvdb keeps waddrmgr's legacy
    sticky bit because wtxmgr deletes credit records on reorg).
  * Annotates `000006_addresses.up.sql` with a schema-level pointer
    so a future contributor reaching for the column finds the ADR.
  * Threads `IsUsed bool` through `db.AddressInfo` and the address-
    read queries via the EXISTS derivation.
  * Makes the pg / sqlite `MarkAddressUsed` adapters no-ops: the
    wallet's normal "record tx" path already inserts the utxos row
    that the derivation reads. The interface method stays on
    `db.AddressStore` for backend symmetry; kvdb still uses it.

Future kvdb-side adapter changes for IsUsed/MarkAddressUsed land on
top of this contract via the `addresses-used-flag` side branch.

Author: yyforyongyu

docs/developer/adr/0011-no-addresses-used-column.md

@@ -0,0 +1,153 @@
+# ADR 0011: No `used` Column on the Addresses Table
+
+## 1. Context
+
+The wallet needs to answer "has this address ever appeared in a
+transaction the wallet has seen?" — a monotonic property used
+by the unused-address scan to enforce privacy (never re-offer a
+previously-published address).
+
+In the legacy kvdb backend this is a sticky bit on each
+managed address (`waddrmgr.ManagedAddress.Used`). It is set
+when the wallet observes the address in a tx and never cleared,
+even when the underlying credit record is rolled back by a
+reorg (wtxmgr deletes credit records on rollback, so the bit
+is the wallet's only durable record).
+
+When the SQL backend was first sketched in PR #1162, an
+equivalent boolean column was proposed on `addresses`. Review
+collapsed it on the grounds of "two sources of truth": the
+utxos table already records whether an address has ever
+received a credit, so a flag on `addresses` duplicates state.
+The conclusion in #1162 was to derive used-ness from the
+`utxos` table at read time and drop the column. Issue #1167
+captures the orthogonal "unbroadcast tx" privacy gap that
+neither approach solves.
+
+A later session reintroduced the column under
+`prep-address-manager-store` (PR #1237) along with a trigger
+preventing the bit from clearing. The motivation was that the
+wallet's unused-address scan needs *monotonic* used-ness —
+which the derived query would lose if a reorg deleted the
+funding row.
+
+Re-examination of the SQL schema after PR #1232 + ADR 0006
+landed makes the picture clear: under the new SQL design, the
+reorg-delete concern does not apply.
+
+- `transactions.block_height INTEGER REFERENCES blocks
+  (block_height) ON DELETE SET NULL` — a reorged tx becomes
+  unconfirmed; the **row stays**. `tx_status` carries the
+  validity state as soft deletion.
+- `utxos.tx_id BIGINT NOT NULL REFERENCES transactions (id) ON
+  DELETE RESTRICT` — the utxo row cannot be deleted while its
+  creating transaction exists.
+- `utxos.spent_by_tx_id BIGINT REFERENCES transactions (id) ON
+  DELETE RESTRICT` — same protection for spent UTXOs.
+- Physical removal of records is an explicit pruning operation
+  the wallet does not perform in normal flows.
+
+Therefore, on the SQL backend:
+
+```sql
+SELECT EXISTS(SELECT 1 FROM utxos WHERE address_id = ?)
+```
+
+is **monotonic by construction** through reorgs, replaces,
+orphanings, and ordinary operation. The flag column on
+`addresses` is genuinely redundant on SQL.
+
+## 2. Decision
+
+The SQL backend (`pg`, `sqlite`) does NOT persist a `used`
+column on `addresses`.
+
+- `db.Store.IsUsed` on SQL backends is answered via the derived
+  EXISTS query above (projected as part of address-read queries
+  for `GetAddress`, `ListAddresses`, etc.).
+- `db.Store.MarkAddressUsed` is a **no-op** on SQL backends.
+  The wallet's normal "record observed tx" path implicitly
+  marks the address used because it inserts the `utxos` row
+  that the derived query reads.
+- The kvdb backend continues to use waddrmgr's legacy `Used()`
+  flag because wtxmgr deletes credit records on reorg and
+  cannot provide the monotonic guarantee without a separate
+  bit. `db.Store.MarkAddressUsed` on kvdb calls
+  `addrStore.MarkUsed(...)` as today.
+
+The `db.AddressInfo.IsUsed` contract field remains. The two
+adapters populate it from different sources but with the same
+semantics from the wallet's perspective.
+
+## 3. Consequences
+
+### Pros
+
+- Single source of truth on SQL (utxos table), removing the
+  drift risk of two booleans encoding the same fact.
+- One fewer column, one fewer migration, one fewer trigger,
+  one fewer sqlc query. Smaller surface, less migration churn.
+- The contract is uniform — wallet code calls
+  `w.store.IsUsed(...)` and `w.store.MarkAddressUsed(...)`
+  regardless of backend.
+
+### Cons
+
+- The SQL adapter pays a per-row EXISTS sub-query cost on
+  address reads. With `idx_utxos_by_address` (defined in
+  `000008_utxos.up.sql`) the cost is a bounded index lookup,
+  negligible for `GetAddress`-style reads and batchable via
+  LEFT JOIN for `ListAddresses`-style scans.
+- The asymmetric backend implementation (derived on SQL, flag
+  on kvdb) is one more thing for a future contributor to
+  understand. Mitigated by:
+  1. A schema-level pointer comment in
+     `000006_addresses.up.sql` next to where someone would
+     consider adding the column.
+  2. Doc comments on `db.Store.IsUsed` and
+     `db.Store.MarkAddressUsed` that explain the asymmetric
+     implementation and point here.
+
+### Orthogonal: the unbroadcast-tx gap
+
+Neither design closes the case where a user constructs (but
+does not broadcast) a tx referencing a fresh address. The
+wallet sees no utxos record and no flag set, so the address
+remains "unused" and can be re-offered. This is issue #1167
+and is independent of where used-ness is stored.
+
+### Future: if kvdb ever survives reorgs
+
+If wtxmgr's destructive-rollback behavior is ever changed (so
+credit records survive reorg the way SQL records do), the
+kvdb-side flag becomes redundant for the same reason. At that
+point the `MarkAddressUsed` contract method could be retired
+entirely. That is out of scope here and would be a future ADR.
+
+## 4. Implementation notes
+
+- Migration `000011_addresses_used.up.sql` and its down-sql
+  variant are deleted from both `pg` and `sqlite` migration
+  directories.
+- The sqlc `MarkAddressUsed` query is removed from
+  `wallet/internal/sql/pg/queries/addresses.sql` and the
+  sqlite mirror.
+- Address-read queries project `is_used` via
+  `EXISTS(SELECT 1 FROM utxos AS u WHERE u.address_id = a.id)`
+  instead of `a.used`.
+- pg/sqlite adapter `Store.MarkAddressUsed` returns `nil`; doc
+  comment cites this ADR.
+- kvdb adapter unchanged.
+- Wallet code (the `addresses-used-flag` side branch) keeps
+  the contract-level routing.
+
+## 5. References
+
+- PR #1162 discussion that first removed the flag
+  (`wallet/internal/db/data_types.go`,
+  `wallet/internal/db/migrations/postgres/000006_addresses.up.sql`
+  threads on the merged PR).
+- PR #1237 thread that reopened the question.
+- ADR 0006 — the soft-delete / ON DELETE RESTRICT schema
+  decisions that make the SQL derivation monotonic.
+- Issue #1167 — orthogonal unbroadcast-tx privacy gap.

docs/developer/adr/README.md

@@ -16,3 +16,4 @@ ADRs serve as a historical log of important design choices, providing context fo
 - [ADR 0008: Integration Test Framework](./0008-integration-test-framework.md) - Defines a modular integration test framework for chain and database backend permutations.
 - [ADR 0009: Single-Passphrase Encryption Model](./0009-single-passphrase-encryption.md) - Adopts a single-passphrase model that encrypts private data only while keeping public wallet metadata in plaintext.
 - [ADR 0010: Keyvault Encryption Layer](./0010-keyvault-encryption-layer.md) - Defines an in-memory keyvault boundary for lock state, key lifecycle, and encryption orchestration between domain logic and SQL persistence.
+- [ADR 0011: No `used` Column on the Addresses Table](./0011-no-addresses-used-column.md) - Records the decision that the SQL backend derives address used-ness from the utxos table (monotonic by ADR 0006's soft-delete schema) rather than persisting a separate column. The kvdb backend continues to use waddrmgr's legacy sticky-bit because wtxmgr deletes credit records on reorg.

wallet/internal/db/addresses_common.go

@@ -220,6 +220,12 @@ type AddressInfoRow[TypeID, OriginIDType any] struct {
 	// PubKey is the public key. Zero value for derived addresses.
 	PubKey []byte
 
+	// IsUsed is the monotonic on-chain-usage flag persisted with the
+	// address row. The address store keeps this in sync with the legacy
+	// MarkUsed semantics so unused-address scans never re-derive a key
+	// that briefly appeared in a confirmed transaction.
+	IsUsed bool
+
 	// IDToAddrType converts TypeID to AddressType with validation.
 	IDToAddrType func(TypeID) (AddressType, error)
 
@@ -521,6 +527,7 @@ func AddressRowToInfo[TypeID, OriginIDType any](
 		PubKey:               row.PubKey,
 		HasScript:            row.HasScript,
 		IsWatchOnly:          isWatchOnly,
+		IsUsed:               row.IsUsed,
 	}, nil
 }
 

wallet/internal/db/data_types.go

@@ -652,6 +652,18 @@ type AddressInfo struct {
 	// IsWatchOnly indicates whether the address belongs to a watch-only
 	// wallet or does not have private keys.
 	IsWatchOnly bool
+
+	// IsUsed reports whether the address has ever been associated with
+	// an on-chain transaction the wallet has observed. The flag is
+	// monotonic from the wallet's perspective and preserves privacy by
+	// keeping the address out of unused-address scans even after a
+	// reorg.
+	//
+	// Backends populate this field from different sources (see
+	// ADR 0011): SQL backends derive it from the utxos table at read
+	// time; the kvdb backend reads waddrmgr's legacy sticky `Used`
+	// bit.
+	IsUsed bool
 }
 
 // AddressSecret contains sensitive encrypted material for an address.
@@ -1283,3 +1295,20 @@ func (p BalanceParams) Validate() error {
 
 // LockID represents a unique context-specific ID assigned to an output lock.
 type LockID [32]byte
+
+// MarkAddressUsedParams identifies a single address that should be flagged as
+// having been observed in an on-chain transaction. The Store treats this as a
+// monotonic write: setting the flag to true is permanent. Callers may re-issue
+// the request safely; the operation is idempotent.
+type MarkAddressUsedParams struct {
+	// WalletID scopes the lookup to one wallet so script_pub_key collisions
+	// across wallets cannot cross-flag rows.
+	//
+	// NOTE: uint32 is used to ensure compatibility with standard SQL
+	// databases (signed 64-bit integers).
+	WalletID uint32
+
+	// ScriptPubKey identifies the address row by its plaintext locking
+	// script. The wallets table guarantees uniqueness within a wallet.
+	ScriptPubKey []byte
+}

wallet/internal/db/interface.go

@@ -328,6 +328,23 @@ type AddressStore interface {
 	// GetAddressType returns the AddressTypeInfo associated with the given
 	// address type identifier. An error is returned if the type is unknown.
 	GetAddressType(ctx context.Context, id AddressType) (AddressTypeInfo, error)
+
+	// MarkAddressUsed marks the address as having appeared in a wallet-
+	// observed transaction. Backend semantics are asymmetric (see
+	// ADR 0011):
+	//
+	//   - SQL backends (pg, sqlite): no-op. Used-ness is derived from
+	//     the utxos table at read time; the wallet's normal "record tx"
+	//     path inserts the utxos row that the derivation reads.
+	//
+	//   - kvdb backend: flips waddrmgr's legacy sticky `Used` bit
+	//     because wtxmgr deletes credit records on reorg and cannot
+	//     provide a monotonic guarantee on its own.
+	//
+	// In both cases the operation is idempotent. Calls for an unknown
+	// (WalletID, ScriptPubKey) pair return nil so chain reorgs that
+	// surface unowned scripts do not propagate failures.
+	MarkAddressUsed(ctx context.Context, params MarkAddressUsedParams) error
 }
 
 // TxStore defines the database actions for managing transaction records.

wallet/internal/db/kvdb/addressstore.go

@@ -68,3 +68,10 @@ func (s *Store) GetAddressType(ctx context.Context,
 
 	return db.AddressTypeInfo{}, notImplemented(ctx, "GetAddressType")
 }
+
+// MarkAddressUsed is not yet implemented for kvdb.
+func (s *Store) MarkAddressUsed(ctx context.Context,
+	_ db.MarkAddressUsedParams) error {
+
+	return notImplemented(ctx, "MarkAddressUsed")
+}

wallet/internal/db/pg/addresses.go

@@ -410,6 +410,7 @@ func addressRowToInfo[T addressInfoRow](ctx context.Context, q *sqlc.Queries,
 		AddressIndex: base.AddressIndex,
 		ScriptPubKey: base.ScriptPubKey,
 		PubKey:       base.PubKey,
+		IsUsed:       base.IsUsed,
 		IDToAddrType: db.IDToAddressType[int16],
 		IDToOrigin:   db.IDToOrigin[int16],
 	})
@@ -471,3 +472,14 @@ func buildAddressPageParams(
 
 	return params
 }
+
+// MarkAddressUsed is a no-op on SQL backends. Address used-ness is
+// derived from the utxos table at read time, not stored as a flag, so
+// no separate mark step is needed — the wallet's normal "record tx"
+// path inserts the utxos row that the IsUsed derivation reads. See
+// ADR 0011.
+func (s *Store) MarkAddressUsed(_ context.Context,
+	_ db.MarkAddressUsedParams) error {
+
+	return nil
+}

wallet/internal/db/sqlite/addresses.go

@@ -404,6 +404,7 @@ func addressRowToInfo[T addressInfoRow](ctx context.Context, q *sqlc.Queries,
 		AddressIndex:      base.AddressIndex,
 		ScriptPubKey:      base.ScriptPubKey,
 		PubKey:            base.PubKey,
+		IsUsed:            base.IsUsed == 1,
 		IDToAddrType:      db.IDToAddressType[int64],
 		IDToOrigin:        db.IDToOrigin[int64],
 	})
@@ -462,3 +463,14 @@ func buildAddressPageParams(
 
 	return params
 }
+
+// MarkAddressUsed is a no-op on SQL backends. Address used-ness is
+// derived from the utxos table at read time, not stored as a flag, so
+// no separate mark step is needed — the wallet's normal "record tx"
+// path inserts the utxos row that the IsUsed derivation reads. See
+// ADR 0011.
+func (s *Store) MarkAddressUsed(_ context.Context,
+	_ db.MarkAddressUsedParams) error {
+
+	return nil
+}

wallet/internal/sql/pg/migrations/000006_addresses.up.sql

@@ -1,6 +1,13 @@
 -- Migration note: Intentionally NOT idempotent (no "IF NOT EXISTS").
 -- This ensures migration tracking stays accurate and fails loudly if run twice.
 
+-- This table intentionally does NOT include a `used` column.
+-- An address's used-ness is derived from the utxos table
+-- (EXISTS(SELECT 1 FROM utxos WHERE address_id = ?)). The derivation
+-- is monotonic because utxo rows are preserved through reorgs via
+-- tx_status soft-delete (see ADR 0006) and ON DELETE RESTRICT. See
+-- ADR 0011 for the full design rationale.
+--
 -- Addresses table stores all addresses under each account. Addresses can be
 -- either HD-derived (following BIP32/BIP44 derivation paths) or imported from
 -- external sources (e.g., watch-only addresses, hardware wallet addresses).

wallet/internal/sql/pg/queries/addresses.sql

@@ -21,6 +21,7 @@ SELECT
     a.script_pub_key,
     a.pub_key,
     a.created_at,
+    EXISTS(SELECT 1 FROM utxos AS u WHERE u.address_id = a.id) AS is_used,
     acc.origin_id,
     w.is_watch_only AS wallet_is_watch_only,
     (s.encrypted_priv_key IS NOT NULL)::BOOLEAN AS has_private_key,
@@ -88,6 +89,7 @@ SELECT
     a.script_pub_key,
     a.pub_key,
     a.created_at,
+    EXISTS(SELECT 1 FROM utxos AS u WHERE u.address_id = a.id) AS is_used,
     acc.origin_id,
     w.is_watch_only AS wallet_is_watch_only,
     (s.encrypted_priv_key IS NOT NULL)::BOOLEAN AS has_private_key,
@@ -112,3 +114,4 @@ WHERE
     )
 ORDER BY a.id
 LIMIT sqlc.arg('page_limit')::BIGINT;
+