A Bitcoin Core coin-selection lock is not a blockchain timelock

Explainer5 min read

Understand Bitcoin Core’s local coin-selection locks, manual input selection and persistence across restart. A locked-outpoint list is not a blockchain timer.

Brokzi compares fictional wallet-local exclusion tags before and after restart. Neither tag adds a blockchain spending condition.
AI-assisted editorial illustration · Brokzi
On this page

A Bitcoin Core wallet can skip an unspent output because of a local coin-selection lock, even though that lock added no new spending condition to the blockchain. Think of a “leave this one out” tag in the wallet’s inventory. It is not a timer attached to the bitcoin.

This explanation follows Bitcoin Core v32.1, pinned to commit f0de87f0. The linked exported RPC documentation is 32.0.0, a separate version label. The behavior below is cross-checked against the v32.1 implementation; it is not a promise about every wallet or interface.

What does a Bitcoin Core coin lock change?

A “coin” here means an unspent transaction output, or UTXO. Its outpoint identifies a transaction and an output number. For the record structure, see Bitcoin inputs and outputs.

lockunspent changes the selected wallet’s local locked-outpoint records. In the normal automatic funding path, AvailableCoins skips a wallet-locked outpoint when the lock filter is enabled. That filter is enabled by default. See the RPC contract and v32.1 selection code.

This operation does not add a script or transaction time condition to the output. Consensus finality and relative-lock checks use transaction fields and chain context, rather than this wallet’s lock map. The consensus transaction checks are a separate mechanism. Our Bitcoin locktime explainer covers those conditions without treating them as confirmation appointments.

Can an explicitly selected input follow a different path?

Yes. In the pinned implementation, FetchSelectedInputs processes explicitly preselected inputs separately from automatic candidate selection. That path does not apply the automatic wallet-lock exclusion. Other requirements still matter; the code can, for example, reject a preselected input it cannot solve for size estimation.

Passing that filter is not proof of signing capability, a valid completed transaction or confirmation. A local coin lock therefore does not prevent every possible spend. Nor does this code comparison establish what every GUI will let someone select.

The RPC help’s shorthand about manual selection should not be read as a guarantee that highlighting a coin immediately clears its lock. In the implementation, CWallet::AddToSpends calls UnlockCoin when recording a spend of the outpoint. Selecting an input is not itself that spend record. See the selection path and wallet bookkeeping.

Which local lock remains after restart?

For a fresh lock with persistence omitted or false, the record is memory-only. It disappears when the node exits. A fresh lock successfully written with persistence enabled is stored in that wallet’s database and reloaded with it. Restart alone is therefore not a universal way to clear all coin locks.

The wallet implementation separates its in-memory map from the database write. The database code writes and reloads locked outpoints.

Use two deliberately invalid teaching identifiers, DEMO-A:0 and DEMO-B:1. They represent unrelated, otherwise eligible, confirmed non-mining outputs. Each lock is fresh, the persistent write succeeds, and the later observation follows a restart with the same wallet database.

Teaching outpointFresh local lock typeDefault automatic selection before restartLocal lock record after restart
DEMO-A:0Default, memory-onlySkips this outputCleared
DEMO-B:1Saved to the wallet databaseSkips this outputReloaded

This is a declared state example, not RPC output or an executed experiment. No amounts are needed. Neither row creates a new consensus spending condition.

Assume no intervening spend, explicit input selection, unlock, write failure or database replacement. The example does not establish every result of changing an existing lock between persistence modes, restoring a backup or loading another wallet. Removing a local exclusion also does not prove all other spending requirements pass.

What can a locked-outpoint list tell you?

listlockunspent reports the selected wallet’s locked outpoints as txid and vout. The 32.0.0 result reference and v32.1 RPC implementation show those fields.

The listing has no per-entry persistence flag and no scheduled unlock time. Seeing an entry alone cannot tell you whether it will survive restart. An absent entry does not prove that the wallet can sign for it or that a proposed spend satisfies consensus rules.

Read the label in its proper scope: which wallet, which selection path, which storage mode, and which genuine spending conditions? A local exclusion record answers a wallet-selection question. The blockchain does not acquire a new timer because that record exists.

Sources

Full official documentation and pinned source were checked on 18 November 2026. The v32.1 tag resolved to the cited commit. RPC pages are exported from 32.0.0 and are not labeled v32.1 documentation. Related official functional-test source was read, not executed. No wallet, node, RPC operation, coin lock/unlock, transaction, PSBT, signing action, key, real address or real transaction ID was used or constructed.

See something wrong? Brokzi logs material changes. Prepare a correction note.

About the byline

Brokzi Editorial

The accountable byline for Brokzi’s explainers, definitions, news notes, and corrections.

Editorial responsibility →