Skip to content

Class BSV::Wallet::ReplenishmentWorker

Inherits: Object

Background thread that replenishes a {LocalPool} when it runs low.

ReplenishmentWorker loops on a condition variable with a configurable interval timeout. It wakes either on timeout or when signalled by {LocalPool#acquire} (via {#signal}).

Each wake cycle computes the deficit between the pool's target count and its current available count. When a deficit exists, it calls {Client#create_action} to fund new pool outputs.

BRC-29 derivation

Pool outputs are created with fresh BRC-29 derivation metadata so auto_fund_and_create can later identify and spend them. The logic is inlined (not delegated to {ChangeGenerator}) to keep the public API surface of that class clean and avoid coupling to its private internals.

Thread safety

+@mutex+ and +@cv+ guard +@running+ and the condition variable. All external entry points (start, stop, signal) are safe to call from any thread.

Error handling

replenish rescues both {BSV::Wallet::WalletError} and StandardError. Errors are logged to +$stderr+ and the cycle continues — a transient failure (e.g. insufficient funds) does not crash the worker thread.

Constants

BRC29_PROTOCOL_ID

BRC-29 protocol identifier — matches {ChangeGenerator::BRC29_PROTOCOL_ID}.

Public Instance Methods

initialize(pool:, wallet_client:, interval: = 60)

  • @param pool [LocalPool] the pool to replenish
  • @param wallet_client [Client] wallet used to fund new outputs
  • @param interval [Integer, Float] seconds between replenishment checks (default: 60)
  • @return [ReplenishmentWorker] a new instance of ReplenishmentWorker

signal()

Wakes the worker for an immediate replenishment check.

Non-blocking — returns immediately whether or not the thread is sleeping. Safe to call before start or after stop. - @return [void]

start()

Starts the background replenishment thread.

Idempotent — calling start when already running has no effect. - @return [self]

stop()

Stops the background thread.

Sets +@running+ to false, wakes the thread via the condition variable, and joins it with a 5-second timeout. - @return [void]