An application using Bitcoin Core may reserve an unspent output for a payment it plans to build later. Whether that reservation survives a node restart depends on how the application calls lockunspent. Version 30.0 documents a database-backed option alongside the default memory-only behaviour.
| What you need to know |
|---|
| Locked outputs are excluded from the wallet's automatic coin selection. |
| Reservations use memory by default and clear when the node stops or fails. |
| The persistent option writes reservations to the wallet database for loading at startup. |
| Manually selecting a reserved coin automatically unlocks it. |
The version matters here: the commands and behaviour below refer to the Bitcoin Core 30.0 lockunspent RPC documentation. The example concerns wallet software managing its own available outputs. It does not assume a particular exchange, hardware wallet or graphical interface exposes the same controls.
One output, two restart paths
An output is identified by its transaction ID and output index, represented by txid and vout. In the RPC arguments, unlock=false requests a reservation. The optional persistent argument defaults to false; setting it to true stores the reservation in the wallet database so it can be loaded when the node starts.
Follow a hypothetical output through both paths. With the default call, automatic selection skips it during the current process, but a stop or crash clears that reservation. With persistence enabled, startup reloads the reservation from the database. An application that keeps a payment queue across restarts can therefore align the wallet’s selection state with that queue, rather than assuming the memory state survived.
This comparison assumes the output remains unspent and available to the same wallet. Persistence describes the stored reservation. It does not guarantee that a proposed payment will remain valid or that another transaction cannot consume the output.
Manual selection changes the reservation
Core also documents that manually selected coins are automatically unlocked. Explicitly choosing the reserved output for a transaction therefore has a different result from letting the wallet choose inputs automatically. Application code needs to account for both paths when maintaining its payment queue.
That distinction makes the reservation a wallet coin-selection control. It would be a mistake to infer a Bitcoin protocol timelock or a freeze enforceable against every spender: the documented manual-selection path already shows why the automatic-selection restriction has a narrower scope.
For deliberate release, unlock=true clears the reservation, including a persistent one. The documentation also allows unlocking without an output list, which releases all currently locked outputs. A workflow intended to release one queue entry should therefore supply that entry’s outpoint rather than accidentally taking the all-outputs path.
The operational choice is made when the reservation is created: use the database-backed path when that selection state needs to survive a restart, and track later explicit selection or release as changes to the same queue entry.
