Skip to content

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 or broadcast - @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

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