Class BSV::Registry::Client ¶

Inherits: Object

Client for managing on-chain registry definitions for protocols, baskets, and certificate types on the BSV overlay network.

Registry operators use this client to establish canonical references for basket IDs, protocol specifications, and certificate schemas via PushDrop-based UTXOs.

All overlay dependencies (broadcaster, resolver) are injectable for testing.

@example Register a new basket definition

client = BSV::Registry::Client.new(wallet: my_wallet)
data   = BSV::Registry::BasketDefinitionData.new(
  basket_id:         'my-basket',
  name:              'My Basket',
  icon_url:          'https://example.com/icon.png',
  description:       'Stores my tokens',
  documentation_url: 'https://example.com/docs'
)
result = client.register_definition(BSV::Registry::DefinitionType::BASKET, data)

@example Resolve basket definitions

records = client.resolve(BSV::Registry::DefinitionType::BASKET, { basket_id: 'my-basket' })

Public Instance Methods¶

initialize(wallet:, originator: = nil, broadcaster: = nil, resolver: = nil) ¶

• @param wallet [#get_public_key, #get_network, #create_action, #sign_action, #list_outputs] BRC-100 wallet interface
• @param originator [String, nil] optional FQDN of the originating application
• @param broadcaster [BSV::Overlay::TopicBroadcaster, nil] injectable broadcaster; built from the wallet's network preset when nil
• @param resolver [BSV::Overlay::LookupResolver, nil] injectable lookup resolver; built from the wallet's network preset when nil
• @return [Client] a new instance of Client

list_own_registry_entries(definition_type) ¶

Lists the registry operator's own published definitions for the given type.

Queries the wallet for spendable outputs in the appropriate basket, then parses the PushDrop scripts back into structured definition data. - @param definition_type [String] one of {DefinitionType} constants - @return [Array] the operator's own registered definitions

register_definition(definition_type, data) ¶

Publishes a new on-chain definition for baskets, protocols, or certificates.

The definition data is encoded in a PushDrop-based UTXO and broadcast to the appropriate overlay topic for the given definition type. - @param definition_type [String] one of {DefinitionType} constants - @param data [BasketDefinitionData, ProtocolDefinitionData, CertificateDefinitionData] structured definition data - @raise [RuntimeError] if the transaction cannot be created - @raise [BSV::Overlay::OverlayError] (or a subclass) if the overlay broadcast fails — see {BSV::Overlay::OverlayBroadcastResult#raise_if_error!} for the mapping - @return [BSV::Overlay::OverlayBroadcastResult]

resolve(definition_type, query) ¶

Resolves registry definitions of a given type using the overlay lookup service. - @param definition_type [String] one of {DefinitionType} constants - @param query [Hash] filter criteria; keys depend on definition type: - basket: basket_id, name, registry_operators - protocol: name, protocol_id, registry_operators - certificate: type, name, registry_operators - @return [Array] matching registered definitions

resolve_basket(query = {}) ¶

Resolves basket registry definitions.

Thin wrapper around {#resolve} for cross-SDK parity with the Go SDK's ResolveBasket method. - @param query [Hash] optional filter criteria: - +:basket_id+ [String] exact basket identifier - +:name+ [String] human-readable basket name - +:registry_operators+ [Array] operator public key hexes - @return [Array] matching registered basket definitions

resolve_certificate(query = {}) ¶

Resolves certificate type registry definitions.

Thin wrapper around {#resolve} for cross-SDK parity with the Go SDK's ResolveCertificate method. - @param query [Hash] optional filter criteria: - +:type+ [String] Base64-encoded certificate type identifier - +:name+ [String] human-readable certificate type name - +:registry_operators+ [Array] operator public key hexes - @return [Array] matching registered certificate type definitions

resolve_protocol(query = {}) ¶

Resolves protocol registry definitions.

Thin wrapper around {#resolve} for cross-SDK parity with the Go SDK's ResolveProtocol method. - @param query [Hash] optional filter criteria: - +:name+ [String] human-readable protocol name - +:protocol_id+ [Array] BRC-43 two-element protocol ID, e.g. +[1, 'protomap']+ - +:registry_operators+ [Array] operator public key hexes - @return [Array] matching registered protocol definitions

revoke_definition(registered_definition) ¶

Revokes an existing registry definition by spending its UTXO.

Verifies that the definition belongs to the current wallet before spending. - @param registered_definition [RegisteredDefinition] the definition to revoke - @raise [RuntimeError] if the definition does not belong to this wallet or the transaction cannot be created - @return [BSV::Overlay::OverlayBroadcastResult]

update_definition(registered_definition, new_data) ¶

Updates an existing registry definition by revoking it and registering new data.

The update is performed as two sequential operations: revoke then register. This is not atomic — if registration fails after revocation, the definition will have been removed without replacement. - @param registered_definition [RegisteredDefinition] the existing definition to replace - @param new_data [BasketDefinitionData, ProtocolDefinitionData, CertificateDefinitionData] new definition data (must be same type as the existing definition) - @raise [ArgumentError] if the definition types do not match - @raise [RuntimeError] if revocation or registration fails - @return [BSV::Overlay::OverlayBroadcastResult] result of the registration broadcast