Skip to content

Class BSV::Identity::Client

Inherits: Object

Client for resolving and publishing identity information on the BSV overlay network.

Wraps wallet discovery and overlay broadcasting to provide a high-level interface for the BSV Identity protocol:

  • Resolve identities by key or attributes via {#resolve_by_identity_key} and {#resolve_by_attributes}.
  • Publicly reveal certificate fields on-chain via {#publicly_reveal_attributes}.
  • Revoke an existing revelation via {#revoke_certificate_revelation}.

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

@example Resolve an identity 

client = BSV::Identity::Client.new(wallet: my_wallet)
identities = client.resolve_by_identity_key(identity_key: pubkey_hex)

@example Publicly reveal certificate fields 

client = BSV::Identity::Client.new(wallet: my_wallet, broadcaster: my_broadcaster)
result = client.publicly_reveal_attributes(certificate, fields_to_reveal: ['email'])

Constants

DEFAULT_VERIFIER

Default certificate verifier — raises NotImplementedError because certificate verification depends on BSV::Auth::Certificate, which is a separate HLR.

Public Instance Methods

initialize(wallet:, options: = nil, originator: = nil, certificate_verifier: = nil, broadcaster: = nil, resolver: = nil)

  • @param wallet [#discover_by_identity_key, #discover_by_attributes, #prove_certificate, #create_action, #get_network] BRC-100 wallet interface
  • @param options [ClientOptions, nil] identity protocol options (default: ClientOptions::DEFAULT)
  • @param originator [String, nil] optional FQDN of the originating application
  • @param certificate_verifier [#call, nil] callable that verifies a certificate; defaults to a lambda that raises NotImplementedError
  • @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

publicly_reveal_attributes(certificate, fields_to_reveal:)

Publicly reveals selected fields from a certificate by creating an on-chain identity token and broadcasting it to the overlay network.

The certificate is first optionally verified via the injected verifier, then the wallet proves the selected fields to the "anyone" verifier (PrivateKey(1) public key). A PushDrop locking script is constructed from the certificate JSON plus keyring, and the resulting transaction is broadcast to tm_identity. - @param certificate [Hash] wallet certificate hash - @param fields_to_reveal [Array] field names to include in the revelation - @raise [ArgumentError] if the certificate has no fields or fields_to_reveal is empty - @raise [RuntimeError] if certificate verification fails or create_action returns no tx - @return [BSV::Overlay::OverlayBroadcastResult]

resolve_by_attributes(attributes:, limit: = nil, offset: = nil)

Resolves displayable identities matching specific certificate attribute values.

Delegates to the wallet's discover_by_attributes and maps each returned certificate through {IdentityParser.parse}. - @param attributes [Hash] field name/value pairs to match - @param limit [Integer, nil] maximum number of certificates to return - @param offset [Integer, nil] number of certificates to skip - @return [Array]

resolve_by_identity_key(identity_key:, limit: = nil, offset: = nil)

Resolves displayable identities issued to a given identity key.

Delegates to the wallet's discover_by_identity_key and maps each returned certificate through {IdentityParser.parse}. - @param identity_key [String] compressed public key hex - @param limit [Integer, nil] maximum number of certificates to return - @param offset [Integer, nil] number of certificates to skip - @return [Array]

revoke_certificate_revelation(serial_number)

Revokes a publicly revealed certificate by spending the identity token.

Queries the ls_identity lookup service for the revelation output identified by serial_number, then creates a spending transaction via the wallet and broadcasts it to tm_identity. - @param serial_number [String] Base64 serial number of the certificate revelation to revoke - @raise [RuntimeError] if the revelation cannot be found or the transaction cannot be created - @return [void]