Class BSV::Wallet::Store::Memory ¶

Inherits: Object Includes: BSV::Wallet::Interface::Store

In-memory storage adapter intended for testing and development only.

Stores actions, outputs, and certificates in plain Ruby arrays. All data is lost when the process exits — do not use in production. Use PostgresStore (or another persistent adapter) for production wallets.

Thread safety: a Mutex serialises all state-mutating operations so that concurrent threads cannot select and mark the same UTXO as pending. This makes Store::Memory safe within a single Ruby process.

NOTE: Store::File is NOT process-safe — concurrent processes share no in-memory lock and may read stale state from disk.

Production Warning¶

When RACK_ENV, RAILS_ENV, or APP_ENV is set to production or staging, a warning is emitted to stderr. Suppress it with either:

BSV_MEMORY_STORE_OK=1               # environment variable
Store::Memory.warn_in_production = false  # Ruby flag (e.g. in test setup)

Attributes¶

warn_in_production= [W] ¶

Sets the attribute warn_in_production - @param value the value to set the attribute warn_in_production to.

Public Class Methods¶

warn_in_production?() ¶

Controls whether the production-environment warning is emitted. Set to false in test suites to silence the warning globally. - @return [Boolean]

Public Instance Methods¶

count_actions(query) ¶

Not documented.

count_certificates(query) ¶

Not documented.

count_outputs(query) ¶

Not documented.

delete_action(txid) ¶

Not documented.

delete_certificate(type:, serial_number:, certifier:) ¶

Not documented.

delete_output(outpoint) ¶

Not documented.

find_actions(query) ¶

Not documented.

find_certificates(query) ¶

Not documented.

find_outputs(query) ¶

Not documented.

find_proof(txid) ¶

Not documented.

find_setting(key) ¶

Retrieves a named wallet setting. - @param key [String] the setting name - @return [Object, nil] the stored value, or nil if not found

find_spendable_outputs(basket: = nil, min_satoshis: = nil, sort_order: = :desc) ¶

Returns only outputs whose effective state is :spendable.

Legacy outputs that carry no :state key are treated as spendable when spendable: is not explicitly false.

This method is wrapped in the same mutex as {#update_output_state} so that a thread cannot select a UTXO that another thread is simultaneously marking as pending. - @param basket [String, nil] restrict to this basket when provided - @param min_satoshis [Integer, nil] exclude outputs below this value - @param sort_order [Symbol] +:asc+ or +:desc+ (default +:desc+, largest first) - @return [Array]

find_transaction(txid) ¶

Not documented.

initialize() ¶

• @return [Memory] a new instance of Memory

lock_utxos(outpoints, reference:, no_send: = false) ¶

Atomically locks the specified outpoints as :pending.

Holds the mutex for the entire operation so no other thread can read or transition these outputs between the check and the lock. - @param outpoints [Array] outpoint identifiers to lock - @param reference [String] caller-supplied pending reference - @param no_send [Boolean] true if this is a no_send lock - @return [Array] outpoints successfully locked

release_stale_pending!(timeout: = 300) ¶

Releases pending locks that have been held longer than timeout seconds.

Each output in :pending state whose :pending_since timestamp is older than timeout seconds is reverted to :spendable and its pending metadata is cleared. - @param timeout [Integer] lock age in seconds before it is considered stale (default 300) - @return [Integer] number of outputs released

store_action(action_data) ¶

Not documented.

store_certificate(cert_data) ¶

Not documented.

store_output(output_data) ¶

Not documented.

store_proof(txid, bump_hex) ¶

Not documented.

store_setting(key, value) ¶

Persists a named wallet setting. - @param key [String] the setting name - @param value [Object] the setting value (must be JSON-serialisable)

store_transaction(txid, tx_hex) ¶

Not documented.

update_action_status(txid, new_status) ¶

• @raise [WalletError]

update_output_basket(outpoint, new_basket) ¶

Reassigns the basket of an existing output without altering any other field. - @param outpoint [String] the outpoint identifier - @param new_basket [String] the target basket name - @raise [BSV::Wallet::WalletError] if the outpoint is not found - @return [Hash] the updated output hash

update_output_state(outpoint, new_state, pending_reference: = nil, no_send: = nil) ¶

Transitions the state of an existing output.

When new_state is :pending, a :pending_since (ISO 8601 UTC) and :pending_reference are attached to the output so stale locks can be detected via {#release_stale_pending!}.

Pass +no_send: true+ to mark the lock as belonging to a no_send transaction; these locks are exempt from automatic stale recovery and must be released explicitly via abort_action.

When transitioning away from :pending, all pending metadata is cleared.

This method is wrapped in a mutex to prevent concurrent transitions on the same output from two threads. - @param outpoint [String] the outpoint identifier - @param new_state [Symbol] +:spendable+, +:pending+, or +:spent+ - @param pending_reference [String, nil] caller-supplied label for the lock - @param no_send [Boolean, nil] true if the lock is for a no_send transaction - @raise [BSV::Wallet::WalletError] if the outpoint is not found