Wallet and consolidation

The wallet block controls how the client reads your node wallet, how many boxes it may hold in flight, and whether it merges small boxes back together. These knobs help control how your wallet is used in the client, and how to deal with UTXO growth inside of it. A miner with a fragmented wallet wants different behaviour from one with a handful of large boxes.

Every default reproduces the constant it replaced, so leaving the block out changes nothing.

Selection and paging#

A wallet of large boxes reaches the byte bound before the count bound, which is why both exist.

Timeouts#

An inventory walk fails rather than returning a prefix. A partial answer would misreport what the wallet holds, and consolidation would then act on the wrong total.

Funding is serialised on one thread, so reservation-timeout-ms bounds the queue behind a slow node read rather than the read itself. Raise it before raising the pool if joins are timing out on a busy node.

In-flight ceilings#

The gap between them is deliberate and it is a reserve. The default of 362 is exactly two full transactions' worth below the ceiling, at 512 - 2 × 75.

That reserve is what a NISP submission or a fraud proof funds itself from while the optional queue is saturated. Without it a long consolidation pass could hold every input the engine owns, and a submission would find nothing to fund a bond with.

Startup refuses max-optional-inputs above max-wallet-inputs and says so. Raising the optional share is what lets a big consolidation pass hold more boxes at once, so raise max-wallet-inputs alongside it or the reserve for critical work shrinks.

Consolidation#

Consolidation merges your own wallet boxes back together. It ships off, because a miner who never fragments their wallet gains nothing from it.

Above target-utxos one pass merges the excess. At or below it nothing happens.

It is the lowest-priority work the engine does. It runs only when nothing else is in flight, so interval-ms is a floor rather than a schedule, and a busy client may go much longer between passes.

min-inputs exists because merging two boxes pays a fee to remove one box. Anything below the floor is not worth building.

Reducing a wallet of thousands#

One transaction removes at most max-inputs - 1 boxes, which is 74 at the defaults. A wallet of several thousand boxes would take many passes at one transaction each.

num-transactions is the lever. Each consolidation spends its own boxes and pays its own fee, and they do not chain, so a rejection costs only its own transaction rather than invalidating the rest.

Next steps#

• Collateral and emission: the work that spends what this wallet selects.
• Synchronization and storage: the other large background subsystem.