# Class BSV::Network::Provider <a id="class-BSV-Network-Provider"></a>

**Inherits:** `Object`

Provider is a named configuration container that hosts one or more Protocol
instances and dispatches commands to the appropriate protocol.

Protocols are registered via a block DSL or by calling <code>#protocol</code>
directly after construction. For each command symbol, the first-registered
protocol that serves it wins (first-registered-wins, no warning on
duplicates).

## Example

    gorillapool = BSV::Network::Provider.new('GorillaPool') do |p|
      p.protocol Protocols::ARC,         base_url: 'https://arcade.gorillapool.io'
      p.protocol Protocols::Chaintracks, base_url: 'https://arcade.gorillapool.io'
      p.protocol Protocols::Ordinals,    base_url: 'https://ordinals.gorillapool.io'
    end

    result = gorillapool.call(:broadcast, tx)
    result.http_success?  # => true

## Attributes
### `auth` [R] <a id="attribute-i-auth"></a> <a id="auth-instance_method"></a>
Returns the value of attribute auth.

### `name` [R] <a id="attribute-i-name"></a> <a id="name-instance_method"></a>
Returns the value of attribute name.

### `rate_limit` [R] <a id="attribute-i-rate_limit"></a> <a id="rate_limit-instance_method"></a>
Returns the value of attribute rate_limit.

## Public Instance Methods
### `authenticated?()` <a id="method-i-authenticated-3F"></a> <a id="authenticated?-instance_method"></a>
Returns `true` when the provider is configured with authentication credentials
(i.e. `auth` is not <code>:none</code> and not an empty hash).
- **@return** [Boolean]

### `call(command_name)` <a id="method-i-call"></a> <a id="call-instance_method"></a>
Dispatches a command to the first-registered protocol that serves it.
- **@param** `command_name` [Symbol, String] command to invoke
- **@param** `*` [Array] positional arguments forwarded to the protocol
- **@param** `**` [Hash] keyword arguments forwarded to the protocol
- **@raise** [ArgumentError] when no registered protocol serves the command
- **@return** [ProtocolResponse]

### `capability_matrix()` <a id="method-i-capability_matrix"></a> <a id="capability_matrix-instance_method"></a>
Returns a hash mapping each protocol instance to the sorted list of commands
it actually serves within this provider (respecting first-registered-wins — a
protocol that lost a command to an earlier registration is not listed for that
command).

Protocols that serve no commands in this provider are omitted.
- **@return** [Hash{Protocol => Array<Symbol>}]

### `commands()` <a id="method-i-commands"></a> <a id="commands-instance_method"></a>
Returns the set of all command symbols available on this provider.
- **@return** [Set<Symbol>]

### `initialize(name, auth: = :none, rate_limit: = nil, &block)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
- **@param** `name` [String] human-readable provider name (e.g. 'GorillaPool')
- **@param** `auth` [Hash, Symbol] authentication config or +:none+ (default: +:none+).
An empty hash or +nil+ is treated as +:none+.
- **@param** `rate_limit` [Numeric, nil] maximum requests per second (+nil+ = unlimited)
- **@param** `block` [Proc] optional configuration block — yields +self+
- **@return** [Provider] a new instance of Provider

### `protocol(klass)` <a id="method-i-protocol"></a> <a id="protocol-instance_method"></a>
Registers a protocol class with the provider.

The class is instantiated with the supplied `kwargs`. Its commands are
indexed: each command not yet in the index is mapped to this instance.
Commands already in the index are left unchanged (first-registered wins).

The provider remains mutable — `protocol` may be called after block execution.
- **@param** `klass` [Class] a Protocol subclass
- **@param** `**` [Hash] keyword arguments forwarded to +klass.new+
- **@return** [Protocol] the newly created protocol instance

### `protocol_for(command_name)` <a id="method-i-protocol_for"></a> <a id="protocol_for-instance_method"></a>
Returns the protocol instance that serves a given command, or nil if no
registered protocol handles it.
- **@param** `command_name` [Symbol, String]
- **@return** [Protocol, nil]

### `protocols()` <a id="method-i-protocols"></a> <a id="protocols-instance_method"></a>
Returns a frozen copy of the registered protocol instances, in registration
order.
- **@return** [Array<Protocol>]

### `to_s()` <a id="method-i-to_s"></a> <a id="to_s-instance_method"></a>
Returns a human-readable representation of the provider.
- **@return** [String]