fix(blockvalidation): release pooled txMap on every Block.Valid exit path

Address PR bsv-blockchain#886 review (Copilot + claude-code-review confirmed Major):
the pooled txMap allocated inside checkDuplicateTransactions was only
returned to the size-class pool on the success path. Any error between
the allocation and the final cleanup (a checkDuplicateTransactions
worker error, the txMap.Flush failure, or any validOrderAndBlessed
error) returned from Block.Valid with b.txMap still pointing at the
multi-GB pooled instance. At 654M-tx scale each leaked map pins ~30 GB
of backing storage on the Block until GC, which may not run for a
long time if the Block is held by the lastValidatedBlocks cache.

Extract the cleanup into a (b *Block).releaseTxMap helper (nil-safe,
idempotent, handles disk-backed / pooled-in-memory / generic Closer)
and call it via `defer` from Block.Valid immediately before invoking
checkDuplicateTransactions. The defer fires on every exit path, so
errors no longer leak the map.

Also address Copilot Minor on batchKeysPool: document the workload
assumption (uniform SetMinedMulti batch sizes within a single Store's
lifetime) and explain when size-class bucketing would become necessary.

Author: icellan

model/Block.go

@@ -537,6 +537,15 @@ func (b *Block) Valid(ctx context.Context, logger ulogger.Logger, subtreeStore S
 	// CVE-2012-2459 guard — runs unconditionally so future callers passing nil subtreeStore
 	// don't silently skip dedup. checkDuplicateTransactions iterates SubtreeSlices in memory
 	// and does not need the subtree store directly.
+	//
+	// b.txMap is allocated inside checkDuplicateTransactions (possibly mid-execution
+	// when a worker fails). The deferred releaseTxMap below ensures the pooled
+	// in-memory variant is returned to the pool on *every* exit path — including
+	// errors from checkDuplicateTransactions, the flush below, and
+	// validOrderAndBlessed. releaseTxMap is nil-safe, idempotent, and handles
+	// all three b.txMap variants (disk-backed, pooled in-memory, generic Closer).
+	defer b.releaseTxMap()
+
 	err = b.checkDuplicateTransactions(ctx, logger, settings.Block.CheckDuplicateTransactionsConcurrency, settings.Block.DiskMapDirs)
 	if err != nil {
 		return false, err
@@ -570,24 +579,36 @@ func (b *Block) Valid(ctx context.Context, logger ulogger.Logger, subtreeStore S
 		}
 	}
 
-	// close and release the txMap
+	return true, nil
+}
+
+// releaseTxMap returns b.txMap to the pool (in-memory variant) or closes the
+// disk-backed map, then nils b.txMap. Idempotent and nil-safe: safe to call
+// multiple times or before b.txMap is ever assigned. Invoked via defer from
+// Block.Valid so the pooled map is reclaimed on every exit path, including
+// errors during checkDuplicateTransactions or validOrderAndBlessed.
+func (b *Block) releaseTxMap() {
+	if b.txMap == nil {
+		return
+	}
+
 	if diskMap, ok := b.txMap.(*DiskTxMapUint64); ok {
 		ReportTxMapStats(diskMap.Stats())
 		_ = diskMap.Close()
 		ClearTxMapStats()
 	} else if poolable, ok := b.txMap.(*txmap.SplitSwissMapUint64); ok {
 		// Return the pooled in-memory map for reuse on the next block.
-		// transactionCountUint32 was computed at Get time; recompute the
-		// same way so the map lands in the matching size-class pool.
+		// b.TransactionCount was set in GetAndValidateSubtrees before
+		// checkDuplicateTransactions ran, so it matches the value used at
+		// GetTxMap time and the map lands in the correct size-class pool.
 		if n, err := safeconversion.Uint64ToUint32(b.TransactionCount); err == nil {
 			PutTxMap(poolable, n)
 		}
 	} else if closer, ok := b.txMap.(io.Closer); ok {
 		_ = closer.Close()
 	}
-	b.txMap = nil
 
-	return true, nil
+	b.txMap = nil
 }
 
 // https://en.bitcoin.it/wiki/BIP_0034

stores/utxo/aerospike/set_mined.go

@@ -109,6 +109,15 @@ func putBatchRecordsSlice(s *[]aerospike.BatchRecordIfc) {
 // different (ns, set) — Key only exposes SetValue, which recomputes digest from
 // the existing setName.
 //
+// Workload assumption: SetMinedMulti batch sizes are relatively uniform within
+// a single Store's lifetime (Store lifetime == application lifetime, ~one Store
+// per deployment). Under that assumption the pool's per-Store scoping is the
+// right trade-off: a large batch seeds the pool with a large backing array
+// that subsequent batches reuse, amortizing allocation. sync.Pool's per-GC
+// drainage ages out the slice if the workload permanently shifts to small
+// batches. If multi-tenant or highly variable batch sizes become common,
+// switch to size-class bucketing analogous to model.GetTxMap.
+//
 // On return, the slice length equals `capacity`. Entries from a freshly allocated
 // slice are nil; the caller must initialize each via aerospike.NewKey before use.
 // Entries retained from a prior batch are non-nil and must be reset via SetValue.