# Class BSV::Overlay::TopicBroadcaster <a id="class-BSV-Overlay-TopicBroadcaster"></a>

**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: <code>[]</code>) — 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<String>+ — 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` <a id="constant-SHIP_CACHE_TTL"></a> <a id="SHIP_CACHE_TTL-constant"></a>
Seconds before the SHIP host cache expires.

## Public Instance Methods
### `broadcast(tx)` <a id="method-i-broadcast"></a> <a id="broadcast-instance_method"></a>
Broadcast a transaction to all interested overlay hosts.
- **@param** `tx` [Transaction::Tx] the transaction to broadcast
- **@return** [OverlayBroadcastResult]

### `find_interested_hosts()` <a id="method-i-find_interested_hosts"></a> <a id="find_interested_hosts-instance_method"></a>
Discover overlay hosts interested in the broadcaster's topics via SHIP.

Results are cached for `SHIP_CACHE_TTL` seconds.
- **@return** [Hash{String => Set<String>}] 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: = {})` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
- **@param** `topics` [Array<String>] 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