Skip to content

Class BSV::Overlay::TopicBroadcaster

Inherits: Object

Broadcasts transactions to overlay topics via SHIP (Service Host Interconnect Protocol).

Discovers interested overlay hosts by querying the ls_ship SLAP service, then dispatches a TaggedBEEF to each host in parallel and verifies acknowledgements according to the configured requirements.

Topic validation

All topics must be non-empty strings beginning with tm_. An empty topics array or a topic without the tm_ prefix raises ArgumentError.

Acknowledgement modes

Three independent ack modes may be combined:

  • require_ack_from_any_host (default: +'all'+) — at least one successful host must satisfy the requirement.
  • require_ack_from_all_hosts (default: []) — every successful host must satisfy the requirement. An empty array disables this check.
  • require_ack_from_specific_hosts (default: +{}+) — named hosts must each satisfy their individual requirement.

Requirement values: * +'all'+ — the host must have acknowledged every one of the broadcaster's topics. * +'any'+ — the host must have acknowledged at least one topic. * +Array+ — the host must have acknowledged all topics in the array.

Host caching

SHIP host discovery results are cached for SHIP_CACHE_TTL seconds (5 minutes) to avoid redundant SLAP queries on repeated broadcasts.

Constants

SHIP_CACHE_TTL

Seconds before the SHIP host cache expires.

Public Instance Methods

broadcast(tx)

Broadcast a transaction to all interested overlay hosts. - @param tx [BSV::Transaction::Transaction] the transaction to broadcast - @return [OverlayBroadcastResult]

find_interested_hosts()

Discover overlay hosts interested in the broadcaster's topics via SHIP.

Results are cached for SHIP_CACHE_TTL seconds. - @return [Hash{String => Set}] map of host URL to set of interested topics

initialize(topics, network_preset: = :mainnet, facilitator: = nil, resolver: = nil, require_ack_from_all_hosts: = [], require_ack_from_any_host: = 'all', require_ack_from_specific_hosts: = {})

  • @param topics [Array] overlay topic names (must start with +tm_+)
  • @param network_preset [Symbol] +:mainnet+, +:testnet+, or +:local+
  • @param facilitator [BroadcastFacilitator, nil] injectable facilitator
  • @param resolver [LookupResolver, nil] injectable resolver
  • @param require_ack_from_all_hosts [Array, String] requirement all hosts must satisfy
  • @param require_ack_from_any_host [String] requirement at least one host must satisfy
  • @param require_ack_from_specific_hosts [Hash] per-host requirements
  • @return [TopicBroadcaster] a new instance of TopicBroadcaster