Class: BSV::KVStore::Global

Inherits:
Object
  • Object
show all
Defined in:
lib/bsv/kv_store/global.rb

Overview

Read-only client for the global KVStore overlay service.

Queries the ls_kvstore lookup service via a Overlay::LookupResolver, decodes PushDrop tokens (5-field legacy and 6-field current formats), verifies the token signature, and returns typed Entry objects.

Set/remove operations require wallet writes and are out of scope — those live in the bsv-wallet gem.

Selector requirement

#get raises ArgumentError unless at least one of key, controller, protocol_id, or a non-empty tags array is supplied in the query.

Always returns Array

#get always returns Array<Entry>, even for single-result selectors such as key controller+. Callers that expect at most one result should use .first.

Silent skipping

Outputs that fail BEEF parsing, PushDrop decoding, field-count validation, or signature verification are silently skipped (matching the TS SDK contract).

Instance Method Summary collapse

Constructor Details

#initialize(network_preset: :mainnet, lookup_resolver: nil, service_name: 'ls_kvstore', proto_wallet: nil) ⇒ Global

Returns a new instance of Global.

Parameters:

  • network_preset (Symbol) (defaults to: :mainnet) —

    :mainnet, :testnet, or :local

  • lookup_resolver (BSV::Overlay::LookupResolver, nil) (defaults to: nil) —

    injectable resolver

  • service_name (String) (defaults to: 'ls_kvstore') —

    lookup service identifier

  • proto_wallet (BSV::Wallet::ProtoWallet, nil) (defaults to: nil) —

    injectable wallet used for signature verification; defaults to ProtoWallet.new(‘anyone’). Tests can substitute a double to avoid allow_any_instance_of.



38
39
40
41
42
 
# File 'lib/bsv/kv_store/global.rb', line 38

def initialize(network_preset: :mainnet, lookup_resolver: nil, service_name: 'ls_kvstore', proto_wallet: nil)
  @lookup_resolver = lookup_resolver || BSV::Overlay::LookupResolver.new(network_preset: network_preset)
  @service_name = service_name
  @proto_wallet = proto_wallet || BSV::Wallet::ProtoWallet.new('anyone')
end

Instance Method Details

#get(query, include_token: false, history: false) ⇒ Array<Entry>

Query the overlay for KVStore entries.

Parameters:

  • query (Hash) —

    selector: :key, :controller, :protocol_id, :tags, :tag_query_mode. At least one of the first four must be present.

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

    populate Token on each entry when true

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

    populate history via Overlay::Historian when true

Returns:

  • (Array<Entry>) —

    matching entries (empty array when nothing matches)

Raises:

  • (ArgumentError) —

    if no selector is provided



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/bsv/kv_store/global.rb', line 52

def get(query, include_token: false, history: false)
  validate_selector!(query)

  question = BSV::Overlay::LookupQuestion.new(
    service: @service_name,
    query: camelise(query)
  )

  answer = @lookup_resolver.query(question)
  return [] unless answer.type == 'output-list'

  answer.outputs.filter_map do |output|
    build_entry(output, include_token: include_token, history: history)
  rescue StandardError
    nil
  end
end