Module: BSV::Wallet::StorageAdapter

Included in:
MemoryStore
Defined in:
lib/bsv/wallet_interface/storage_adapter.rb

Overview

Duck-typed storage interface for wallet persistence.

Include this module in storage adapters and override all methods. The default implementations raise NotImplementedError.

Instance Method Summary collapse

Instance Method Details

#count_actions(_query) ⇒ Object

Raises:

  • (NotImplementedError) 


42
43
44
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 42

def count_actions(_query)
  raise NotImplementedError, "#{self.class}#count_actions not implemented"
end

#count_certificates(_query) ⇒ Object

Raises:

  • (NotImplementedError) 


50
51
52
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 50

def count_certificates(_query)
  raise NotImplementedError, "#{self.class}#count_certificates not implemented"
end

#count_outputs(_query) ⇒ Object

Raises:

  • (NotImplementedError) 


46
47
48
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 46

def count_outputs(_query)
  raise NotImplementedError, "#{self.class}#count_outputs not implemented"
end

#delete_action(_txid) ⇒ Boolean

Removes a stored action by txid.

Parameters:

  • _txid (String) —

    the transaction identifier of the action to remove

Returns:

  • (Boolean) —

    true if the action was deleted, false if not found

Raises:

  • (NotImplementedError) 


86
87
88
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 86

def delete_action(_txid)
  raise NotImplementedError, "#{self.class}#delete_action not implemented"
end

#delete_certificate(type:, serial_number:, certifier:) ⇒ Object

Raises:

  • (NotImplementedError) 


38
39
40
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 38

def delete_certificate(type:, serial_number:, certifier:)
  raise NotImplementedError, "#{self.class}#delete_certificate not implemented"
end

#delete_output(_outpoint) ⇒ Object

Raises:

  • (NotImplementedError) 


26
27
28
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 26

def delete_output(_outpoint)
  raise NotImplementedError, "#{self.class}#delete_output not implemented"
end

#find_actions(_query) ⇒ Object

Raises:

  • (NotImplementedError) 


14
15
16
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 14

def find_actions(_query)
  raise NotImplementedError, "#{self.class}#find_actions not implemented"
end

#find_certificates(_query) ⇒ Object

Raises:

  • (NotImplementedError) 


34
35
36
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 34

def find_certificates(_query)
  raise NotImplementedError, "#{self.class}#find_certificates not implemented"
end

#find_outputs(_query) ⇒ Object

Raises:

  • (NotImplementedError) 


22
23
24
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 22

def find_outputs(_query)
  raise NotImplementedError, "#{self.class}#find_outputs not implemented"
end

#find_proof(_txid) ⇒ Object

Raises:

  • (NotImplementedError) 


58
59
60
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 58

def find_proof(_txid)
  raise NotImplementedError, "#{self.class}#find_proof not implemented"
end

#find_setting(_key) ⇒ Object?

Retrieves a named wallet setting.

Parameters:

  • _key (String) —

    the setting name

Returns:

  • (Object, nil) —

    the stored value, or nil if not found

Raises:

  • (NotImplementedError) 


165
166
167
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 165

def find_setting(_key)
  raise NotImplementedError, "#{self.class}#find_setting not implemented"
end

#find_spendable_outputs(basket: nil, min_satoshis: nil, sort_order: :desc) ⇒ Array<Hash>

Returns only outputs whose effective state is :spendable.

Parameters:

  • basket (String, nil) (defaults to: nil) —

    restrict to this basket when provided

  • min_satoshis (Integer, nil) (defaults to: nil) —

    exclude outputs below this value

  • sort_order (Symbol) (defaults to: :desc) —

    :asc or :desc (default :desc, largest first)

Returns:

  • (Array<Hash>)

Raises:

  • (NotImplementedError) 


132
133
134
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 132

def find_spendable_outputs(basket: nil, min_satoshis: nil, sort_order: :desc)
  raise NotImplementedError, "#{self.class}#find_spendable_outputs not implemented"
end

#find_transaction(_txid) ⇒ Object

Raises:

  • (NotImplementedError) 


66
67
68
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 66

def find_transaction(_txid)
  raise NotImplementedError, "#{self.class}#find_transaction not implemented"
end

#lock_utxos(outpoints, reference:, no_send: false) ⇒ Array<String>

Atomically finds outputs by outpoint and marks them as :pending.

This prevents TOCTOU races where two threads select the same UTXO between find_spendable_outputs and update_output_state. Only outputs still in :spendable state are locked; any that have already transitioned are skipped.

Parameters:

  • outpoints (Array<String>) —

    outpoint identifiers to lock

  • reference (String) —

    caller-supplied pending reference

  • no_send (Boolean) (defaults to: false) —

    true if this is a no_send lock

Returns:

  • (Array<String>) —

    outpoints that were successfully locked

Raises:

  • (NotImplementedError) 


121
122
123
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 121

def lock_utxos(outpoints, reference:, no_send: false)
  raise NotImplementedError, "#{self.class}#lock_utxos not implemented"
end

#release_stale_pending!(timeout: 300) ⇒ Integer

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.

This is a no-op for adapters that do not support pending metadata.

Parameters:

  • timeout (Integer) (defaults to: 300) —

    lock age in seconds before it is considered stale

Returns:

  • (Integer) —

    number of outputs released

Raises:

  • (NotImplementedError) 


147
148
149
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 147

def release_stale_pending!(timeout: 300)
  raise NotImplementedError, "#{self.class}#release_stale_pending! not implemented"
end

#store_action(_action_data) ⇒ Object

Raises:

  • (NotImplementedError) 


10
11
12
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 10

def store_action(_action_data)
  raise NotImplementedError, "#{self.class}#store_action not implemented"
end

#store_certificate(_cert_data) ⇒ Object

Raises:

  • (NotImplementedError) 


30
31
32
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 30

def store_certificate(_cert_data)
  raise NotImplementedError, "#{self.class}#store_certificate not implemented"
end

#store_output(_output_data) ⇒ Object

Raises:

  • (NotImplementedError) 


18
19
20
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 18

def store_output(_output_data)
  raise NotImplementedError, "#{self.class}#store_output not implemented"
end

#store_proof(_txid, _bump_hex) ⇒ Object

Raises:

  • (NotImplementedError) 


54
55
56
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 54

def store_proof(_txid, _bump_hex)
  raise NotImplementedError, "#{self.class}#store_proof not implemented"
end

#store_setting(_key, _value) ⇒ Object

Persists a named wallet setting.

Parameters:

  • _key (String) —

    the setting name

  • _value (Object) —

    the setting value (must be JSON-serialisable)

Raises:

  • (NotImplementedError) 


156
157
158
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 156

def store_setting(_key, _value)
  raise NotImplementedError, "#{self.class}#store_setting not implemented"
end

#store_transaction(_txid, _tx_hex) ⇒ Object

Raises:

  • (NotImplementedError) 


62
63
64
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 62

def store_transaction(_txid, _tx_hex)
  raise NotImplementedError, "#{self.class}#store_transaction not implemented"
end

#update_action_status(_txid, _new_status) ⇒ Hash

Updates the status field of a stored action identified by txid.

Parameters:

  • _txid (String) —

    the transaction identifier of the action to update

  • _new_status (String) —

    the new status value (e.g. ‘failed’, ‘completed’)

Returns:

  • (Hash) —

    the updated action hash

Raises:



77
78
79
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 77

def update_action_status(_txid, _new_status)
  raise NotImplementedError, "#{self.class}#update_action_status not implemented"
end

#update_output_state(_outpoint, _new_state, pending_reference: nil, no_send: nil) ⇒ Object

Transitions the state of an existing output.

When new_state is :pending, pass a pending_reference: string to associate the lock with a specific action. The adapter should record a timestamp (ISO 8601 UTC) alongside the reference so stale locks can be detected and released by #release_stale_pending!.

When transitioning away from :pending, the adapter must clear any stored :pending_since and :pending_reference metadata.

Parameters:

  • _outpoint (String) —

    the outpoint identifier (e.g. “txid.vout”)

  • _new_state (Symbol) —

    one of :spendable, :pending, :spent

  • _pending_reference (String, nil) —

    caller-supplied label for a pending lock

  • _no_send (Boolean, nil) —

    true if the lock belongs to a no_send transaction; these locks are exempt from automatic stale recovery via #release_stale_pending!

Raises:

  • (NotImplementedError) 


106
107
108
 
# File 'lib/bsv/wallet_interface/storage_adapter.rb', line 106

def update_output_state(_outpoint, _new_state, pending_reference: nil, no_send: nil)
  raise NotImplementedError, "#{self.class}#update_output_state not implemented"
end