Class: BSV::Wallet::ReplenishmentWorker

Inherits:
Object
  • Object
show all
Defined in:
lib/bsv/wallet/utxo_pool/replenishment_worker.rb

Overview

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::Transaction#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 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.

Constant Summary collapse

BRC29_PROTOCOL_ID =

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

[2, '3241645161d8'].freeze

Instance Method Summary collapse

Constructor Details

#initialize(pool:, wallet_client:, interval: 60) ⇒ ReplenishmentWorker

Returns a new instance of ReplenishmentWorker.

Parameters:

  • pool (LocalPool) —

    the pool to replenish

  • wallet_client (Client) —

    wallet used to fund new outputs

  • interval (Integer, Float) (defaults to: 60) —

    seconds between replenishment checks (default: 60)



42
43
44
45
46
47
48
49
50
 
# File 'lib/bsv/wallet/utxo_pool/replenishment_worker.rb', line 42

def initialize(pool:, wallet_client:, interval: 60)
  @pool          = pool
  @wallet_client = wallet_client
  @interval      = interval
  @mutex         = Mutex.new
  @cv            = ConditionVariable.new
  @running       = false
  @thread        = nil
end

Instance Method Details

#signal ⇒ void

This method returns an undefined value.

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.



88
89
90
 
# File 'lib/bsv/wallet/utxo_pool/replenishment_worker.rb', line 88

def signal
  @mutex.synchronize { @cv.signal }
end

#start ⇒ self

Starts the background replenishment thread.

Idempotent — calling start when already running has no effect.

Returns:

  • (self) 


57
58
59
60
61
62
63
64
65
66
 
# File 'lib/bsv/wallet/utxo_pool/replenishment_worker.rb', line 57

def start
  @mutex.synchronize do
    return self if @running

    @running = true
    @thread  = Thread.new { run_loop }
    @thread.abort_on_exception = false
  end
  self
end

#stop ⇒ void

This method returns an undefined value.

Stops the background thread.

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



74
75
76
77
78
79
80
 
# File 'lib/bsv/wallet/utxo_pool/replenishment_worker.rb', line 74

def stop
  @mutex.synchronize do
    @running = false
    @cv.signal
  end
  @thread&.join(5)
end