BSV blockchainBSV blockchain

How the toolbox tracks UTXOs

@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-100BSV 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 UTXOsUnspent 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 MonitorThe 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:

  • transactions.status

    What the app sees

    The status that listActions reports to the app, from unsigned to completed or failed.

  • proven_tx_reqs.status

    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 P2PKHPay to Public Key Hash, the standard script that locks an output to a key outputs in the default basketA named group of outputs the wallet tracks that carry the wallet’s own BRC-29BRC-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:

Exact match

An output that matches the amount exactly.

Smallest that covers it

The smallest output that covers the amount.

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 BEEFBackground 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 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:

  • acceptDelayedBroadcast: false

    Broadcast right away

    The wallet broadcasts before createAction returns. A successful broadcast moves the proof request to unmined and the transaction to unproven.

  • acceptDelayedBroadcast: true

    Broadcast later by the Monitor, the default

    The proof request starts as unsent and the transaction as unprocessed. The Monitor broadcasts it later.

  • noSend

    Not broadcast

    Without sendWith, both start as nosend and the transaction is not broadcast. It waits for a later sendWith batch.

When a broadcast happens, its result sets both statuses:

Broadcast resultProof requestTransaction
Successunminedunproven
Double spendTwo transactions that spend the same output, where only the first one the network saw is validdoubleSpendfailed
Invalid transactioninvalidfailed
Service errorsendingsending, retried later

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:

  1. unsigned

    createAction committed the plan. The inputs are already claimed

  2. unprocessed

    Signed, and not broadcast yet

  3. sending

    Queued for broadcast, or retrying after a service error

  4. unproven

    The network accepted it, and the wallet has no Merkle proof yet

  5. 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

  • 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:

StateWhat sets it
CreatedcreateAction stores the output with spendable: true
VisibleThe parent transaction reaches a status that listOutputs returns
AllocatedAnother createAction claims it as an input, spendable: false
SpentThe spending transaction completes
Visible againThe spending transaction fails, and the wallet releases its inputs
DeadThe parent transaction failed
UnbasketedrelinquishOutput clears its basketId

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:

  • 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. An insertion into default is rejected.

A transaction that arrives with a Merkle proofThe 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:

  • 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.

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