# How the toolbox tracks UTXOs

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

How @bsv/wallet-toolbox records each output from the moment createAction plans it until a later transaction spends it, and what the Monitor settles in the background.

import BlueTable from '/snippets/BlueTable.jsx';
import UtxoRecords from '/snippets/UtxoRecords.jsx';
import UtxoStatusFlow from '/snippets/UtxoStatusFlow.jsx';
import MonitorTasks from '/snippets/MonitorTasks.jsx';
import UtxoCards from '/snippets/UtxoCards.jsx';

`@bsv/wallet-toolbox` keeps a storage record for every output its wallet owns, from the moment `createAction` plans it until a later transaction spends it. BRC-100 (BSV Request for Comments 100, the standard interface between apps and wallets) defines what each wallet method accepts and returns, and the toolbox decides what happens in between: which UTXOs (Unspent transaction output) fund a transaction, which rows change, and which status the transaction and its outputs end up in. Knowing this explains why an output is missing from `listOutputs`, why the balance comes back after a failed broadcast, and why a transaction stays `unproven` until the Monitor (The toolbox component that broadcasts queued transactions, gathers proofs and repairs wallet state in the background) finds its proof. This page was written against `@bsv/wallet-toolbox` 2.14.

## Two statuses follow every transaction

Each transaction the wallet creates has two records, and each has its own status:

<UtxoRecords />

Each transaction has two status records. transactions.status is what the app sees: the status that listActions reports, from unsigned to completed or failed. proven_tx_reqs.status is what the Monitor works on: the status of the proof request, which tracks the broadcast and the Merkle proof in the background.

They advance together, but they do not use the same set of values.

## How createAction claims the coins

`createAction` plans the funding first and claims it afterwards, so two calls that run at the same time never spend the same coin.

### Planning

The wallet funds a transaction only from managed change, the P2PKH (Pay to Public Key Hash, the standard script that locks an output to a key) outputs in the `default` basket (A named group of outputs the wallet tracks) that carry the wallet's own BRC-29 (BRC-29, the payment protocol between a sender and a recipient, with keys derived by BRC-42) derivation data. Outputs that an app files in its own basket are custom outputs. They are not part of the wallet balance and are never picked to pay a fee.

The candidates must be spendable and not reserved, and their parent transaction must have a status the planner accepts. The planner tries `completed` parents first, then adds `unproven`, then `sending`. For each set, `CanonicalChangeSelector` picks the inputs in this order:

**1. Exact match**

An output that matches the amount exactly.

**2. Smallest that covers it**

The smallest output that covers the amount.

**3. Largest that does not cover it**

The largest output that does not cover the amount.

When two outputs tie, `outputId` decides.

The planner keeps the plan whose BEEF (Background Evaluation Extended Format (BRC-62), a transaction sent with the proof that it is real) costs the least. Change follows the basket's own policy, a target number of UTXOs and a minimum value. A change output worth less than the dust floor, twice the fee of spending a minimal P2PKH input, is not created, and its value goes to the fee.

### Claiming

The claim runs inside one database transaction. The wallet records the new transaction as `unsigned`, locks the chosen outputs, checks that they did not change since planning, and sets each one to `spendable: false` with `spentBy` pointing at the new transaction. From that moment, no other `createAction` can select them.

If another call took the same outputs first, the wallet plans again instead of waiting for the lock. After three failed claims in a row, `createAction` throws `WERR_INVALID_OPERATION`, and the caller can retry.

## From signing to broadcast

When every input already has its unlocking script, `createAction` signs and processes the transaction in the same call and returns the transaction ID. When an input only declares an `unlockingScriptLength`, `createAction` returns a `signableTransaction` with a `reference`, and the app finishes it with `signAction`. Read [What createAction can return](https://bsvblockchain.com/docs/concepts/wallet-model/#what-createaction-can-return) for the app side of these two results.

The wallet keeps pending `signAction` references in the memory of the `Wallet` instance. A reference does not survive a restart and cannot be signed by another process, and `signAction` throws `WERR_NOT_IMPLEMENTED` for a reference it does not know.

Both paths end in `processAction`, which checks the signed transaction against the plan, commits it, and then broadcasts it or queues it. Three options decide the statuses a new transaction gets:

<UtxoCards set="broadcast" />

There are three broadcast options. acceptDelayedBroadcast set to false: the wallet broadcasts before createAction returns, and a successful broadcast moves the proof request to unmined and the transaction to unproven. acceptDelayedBroadcast set to true, the default when the option is omitted: the proof request starts as unsent and the transaction as unprocessed, and the Monitor broadcasts it later. noSend without sendWith: both start as nosend, the transaction is not broadcast, and it waits for a later sendWith batch.

When a broadcast happens, its result sets both statuses:

<BlueTable>

| Broadcast result | Proof request | Transaction |
| --- | --- | --- |
| Success | `unmined` | `unproven` |
| Double spend (Two transactions that spend the same output, where only the first one the network saw is valid) | `doubleSpend` | `failed` |
| Invalid transaction | `invalid` | `failed` |
| Service error | `sending` | `sending`, retried later |

</BlueTable>

A late result never moves a proof request back from `completed` or `unmined`.

## Transaction statuses

These are the values of `transactions.status`. A transaction usually moves along the top row, and the boxes with a blue border are final:

<UtxoStatusFlow />

The usual path of transactions.status is unsigned (createAction committed the plan and the inputs are claimed), then unprocessed (signed, not broadcast yet), then sending (queued for broadcast, or retrying after a service error), then unproven (the network accepted it and the wallet has no Merkle proof yet), then completed (the wallet found and validated its Merkle proof, final). Off the usual path: nosend (signed and kept back by the noSend option), failed (aborted, rejected or abandoned, final unless an operator sets it to unfail) and unfail (set by an operator to retry: unproven if a proof is found, failed if not).

The proof request is final at `completed`, `invalid` or `doubleSpend`. Every other value is still open, and the Monitor keeps working on it.

## What makes an output spendable

No column holds an output's status. The toolbox reads it from four values together, `spendable`, `spentBy`, `basketId`, and the status of the parent transaction.

`listOutputs` returns an output only when `spendable` is true and its parent transaction is `completed`, `unproven`, `nosend` or `sending`. An output of an `unsigned` or `failed` transaction stays hidden, whatever its own `spendable` value. Change is `spendable: true` as soon as the transaction is committed, so the parent status alone decides when it shows up.

An output goes through these states:

<BlueTable>

| State | What sets it |
| --- | --- |
| Created | `createAction` stores the output with `spendable: true` |
| Visible | The parent transaction reaches a status that `listOutputs` returns |
| Allocated | Another `createAction` claims it as an input, `spendable: false` |
| Spent | The spending transaction completes |
| Visible again | The spending transaction fails, and the wallet releases its inputs |
| Dead | The parent transaction failed |
| Unbasketed | `relinquishOutput` clears its `basketId` |

</BlueTable>

`relinquishOutput` only removes the output from its basket. It does not spend the output or make it unspendable. Since `listOutputs` requires a `basket`, an unbasketed output no longer appears in any `listOutputs` result.

## What happens when a transaction fails

`StorageProvider.updateTransactionStatus` is where a transaction's status and its outputs change together. It follows three rules:

- A `completed` transaction, or one with a `provenTxId`, cannot change status.
- This method cannot move a `failed` transaction out of `failed`.
- Moving a transaction to `failed` releases every input it consumed, back to `spendable: true` with no `spentBy`, and makes every output it created unspendable.

Releasing the inputs is optimistic, since most failures are temporary. When the broadcaster confirms that an input is really gone, as with a double spend or a missing input that the network reports as no longer a UTXO, the wallet keeps that input spent, so the next `createAction` does not select it again. Inputs of a transaction rejected as malformed or for its fee stay spendable.

`abortAction` uses the same path. It refuses a transaction that is `completed`, `failed`, `sending` or `unproven`. For a `nosend` transaction with a transaction ID, it first asks the network, because the app may have broadcast it on its own, and refuses when the network reports it as mined or known. When the network services cannot be reached, the abort goes ahead and writes an audit note, so a wallet can still abort offline.

## Adding outputs with internalizeAction

`internalizeAction` is the only method that adds spendable outputs that `createAction` did not plan. The wallet first verifies the transaction and its proofs, then files each output with one of two protocols:

<UtxoCards set="internalize" />

There are two internalizeAction protocols. wallet payment counts in the balance: the wallet checks the BRC-29 derivation of the output, then stores it as managed change in the default basket, where it can fund the next transaction. basket insertion stays out of the balance: the wallet stores the output as a custom output in a named basket, with the app's own instructions and tags, and an insertion into default is rejected.

A transaction that arrives with a Merkle proof (The proof that a transaction is in a block, checked against the block header) is stored as `completed`. Without one, it is stored as `unproven`.

## What the Monitor settles in the background

Every method above returns before the transaction is final. The `Monitor` runs tasks on an interval that broadcast what is waiting, collect proofs and repair state that drifted:

<MonitorTasks />

The Monitor tasks: TaskSendWaiting broadcasts unsent requests and retries stale sending ones. TaskCheckForProofs fetches Merkle proofs for unmined requests and marks the request and the transaction completed. TaskReviewStatus reconciles each transaction with its proof request. TaskReviewDoubleSpends checks whether a reported double spend is real, and sends a false positive to unfail. TaskFailAbandoned moves old transactions that never reached a final status to failed. TaskReviewUtxos repairs change outputs whose state drifted.

The Monitor profile decides which tasks run, and not every task class is registered by default. Delayed broadcasts and the move from `unproven` to `completed` both depend on the Monitor.

## Related articles

To learn more about how a BSV blockchain wallet handles outputs, review these articles:

- [Build a wallet](https://bsvblockchain.com/docs/wallet-dev/)
- [BRC-100 Wallet Interface](https://bsvblockchain.com/docs/concepts/wallet-model/)
- [Send a payment from a server](https://bsvblockchain.com/docs/get-started/quick-start-server/)
- [Understand how your transaction worked](https://bsvblockchain.com/docs/concepts/how-your-payment-worked/)
- [BEEF (BRC-62)](https://bsvblockchain.com/docs/concepts/spv/)