bsv-sdk 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61435802c338981fb3f6fd8d5881aac9aa83b1cdb261f02dc2a9e2ffa1eb8fa7
-  data.tar.gz: '0159ac16ce996bc45503c6342e0ec763d82285968d9b614c209b4c38fc8f2980'
+  metadata.gz: b45240189e3a6531b7273ee4df823490c1f892ae332257743b74783f2e88ef87
+  data.tar.gz: b3ffa3feb075fb232b87a50149af07139ef01d1d80edb03c7e595f758fe01a84
 SHA512:
-  metadata.gz: 17c9ee9dee1b8454aff19753196dbbc9a04463bdca7da03c6c0769d23b9603efb9ef9f4d6fd57b4dc426a99077d5780c9bb5e978e10e6675809301fc9fea1178
-  data.tar.gz: 1a1bbbee8c570c28c8c608320e1db986527d1e847e5c2cb1943c2b35ec10f3fd6de983bea3eb0026b4216caecee2771c246a0ba3eebc497f2bce88325a58002c
+  metadata.gz: 28cb3358d0483ad4574e1ef3a57c6f85f45e4404de0a70faea6e8b431b9c47655b490e73f4779ca74a617e35bcdadd65eb7f5e2cbd9310199a3af494af4a9187
+  data.tar.gz: 5a4f40bf35ba4dc93a260c6729871a165ebb4e468b802f664371bcf0574d3aacf23d91f8ca9634a739af6cd4443e8b264b9256a2888ddfd725289f98a606b3a9

data/lib/bsv/network/arc.rb

@@ -23,11 +23,20 @@ module BSV
       end
 
       # Submit a transaction to ARC.
-      # Returns BroadcastResponse on success, raises BroadcastError on failure.
-      def broadcast(tx)
+      #
+      # @param tx [Transaction] the transaction to broadcast
+      # @param wait_for [String, nil] ARC wait condition — one of
+      #   'RECEIVED', 'STORED', 'ANNOUNCED_TO_NETWORK',
+      #   'SEEN_ON_NETWORK', or 'MINED'. When set, ARC holds the
+      #   connection open until the transaction reaches the requested
+      #   state (or times out). Defaults to nil (no wait).
+      # @return [BroadcastResponse]
+      # @raise [BroadcastError]
+      def broadcast(tx, wait_for: nil)
         uri = URI("#{@url}/v1/tx")
         request = Net::HTTP::Post.new(uri)
         request['Content-Type'] = 'application/octet-stream'
+        request['X-WaitFor'] = wait_for if wait_for
         apply_auth_header(request)
         request.body = tx.to_binary
 

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

data/lib/bsv/wallet_interface/chain_provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Duck-typed interface for blockchain data providers.
+    #
+    # Include this module in chain provider adapters and override all methods.
+    # The default implementations raise NotImplementedError.
+    #
+    # @example Custom provider
+    #   class MyChainProvider
+    #     include BSV::Wallet::ChainProvider
+    #
+    #     def get_height
+    #       # query your node/API
+    #     end
+    #
+    #     def get_header(height)
+    #       # return 80-byte hex block header
+    #     end
+    #   end
+    module ChainProvider
+      # Returns the current blockchain height.
+      # @return [Integer]
+      def get_height
+        raise NotImplementedError, "#{self.class}#get_height not implemented"
+      end
+
+      # Returns the block header at the given height.
+      # @param _height [Integer] block height
+      # @return [String] 80-byte hex-encoded block header
+      def get_header(_height)
+        raise NotImplementedError, "#{self.class}#get_header not implemented"
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/key_deriver.rb

@@ -16,8 +16,10 @@ module BSV
       def initialize(root_key)
         @root_key = if root_key == 'anyone'
                       BSV::Primitives::PrivateKey.new(ANYONE_BN)
-                    else
+                    elsif root_key.is_a?(BSV::Primitives::PrivateKey)
                       root_key
+                    else
+                      raise ArgumentError, "expected a BSV::Primitives::PrivateKey or 'anyone', got #{root_key.class}"
                     end
       end
 

data/lib/bsv/wallet_interface/memory_store.rb

@@ -55,10 +55,11 @@ module BSV
       end
 
       def find_certificates(query)
-        results = @certificates
-        results = results.select { |c| query[:certifiers].include?(c[:certifier]) } if query[:certifiers]
-        results = results.select { |c| query[:types].include?(c[:type]) } if query[:types]
-        apply_pagination(results, query)
+        apply_pagination(filter_certificates(query), query)
+      end
+
+      def count_certificates(query)
+        filter_certificates(query).length
       end
 
       def delete_certificate(type:, serial_number:, certifier:)
@@ -105,6 +106,20 @@ module BSV
         query[:include_spent] ? results : results.reject { |o| o[:spendable] == false }
       end
 
+      def filter_certificates(query)
+        results = @certificates
+        results = results.select { |c| query[:certifiers].include?(c[:certifier]) } if query[:certifiers]
+        results = results.select { |c| query[:types].include?(c[:type]) } if query[:types]
+        results = results.select { |c| c[:subject] == query[:subject] } if query[:subject]
+        if query[:attributes]
+          results = results.select do |c|
+            fields = c[:fields] || {}
+            query[:attributes].all? { |k, v| fields[k] == v || fields[k.to_sym] == v }
+          end
+        end
+        results
+      end
+
       def apply_pagination(results, query)
         offset = query[:offset] || 0
         limit = query[:limit] || 10

data/lib/bsv/wallet_interface/null_chain_provider.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Default chain provider that raises for all blockchain queries.
+    #
+    # Used when a WalletClient is constructed without a chain provider,
+    # allowing the wallet to function for transaction and crypto operations
+    # without requiring a blockchain connection.
+    class NullChainProvider
+      include ChainProvider
+
+      def get_height
+        raise UnsupportedActionError, 'get_height (no chain provider configured)'
+      end
+
+      def get_header(_height)
+        raise UnsupportedActionError, 'get_header_for_height (no chain provider configured)'
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/storage_adapter.rb

@@ -46,6 +46,10 @@ module BSV
       def count_outputs(_query)
         raise NotImplementedError, "#{self.class}#count_outputs not implemented"
       end
+
+      def count_certificates(_query)
+        raise NotImplementedError, "#{self.class}#count_certificates not implemented"
+      end
     end
   end
 end

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -26,11 +26,21 @@ module BSV
       # @return [StorageAdapter] the underlying persistence adapter
       attr_reader :storage
 
+      # @return [ChainProvider] the blockchain data provider
+      attr_reader :chain_provider
+
+      # @return [String] the network ('mainnet' or 'testnet')
+      attr_reader :network
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
       # @param storage [StorageAdapter] persistence adapter (default: MemoryStore)
-      def initialize(key, storage: MemoryStore.new)
+      # @param network [String] 'mainnet' (default) or 'testnet'
+      # @param chain_provider [ChainProvider] blockchain data provider (default: NullChainProvider)
+      def initialize(key, storage: MemoryStore.new, network: 'mainnet', chain_provider: NullChainProvider.new)
         super(key)
         @storage = storage
+        @network = network
+        @chain_provider = chain_provider
         @pending = {}
       end
 
@@ -166,6 +176,224 @@ module BSV
         { accepted: true }
       end
 
+      # --- Blockchain & Network Data ---
+
+      # Returns the current blockchain height from the chain provider.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { height: Integer }
+      def get_height(_args = {}, _originator: nil)
+        { height: @chain_provider.get_height }
+      end
+
+      # Returns the block header at the given height from the chain provider.
+      #
+      # @param args [Hash]
+      # @option args [Integer] :height block height
+      # @return [Hash] { header: String } 80-byte hex-encoded block header
+      def get_header_for_height(args, _originator: nil)
+        raise InvalidParameterError.new('height', 'a positive Integer') unless args[:height].is_a?(Integer) && args[:height].positive?
+
+        { header: @chain_provider.get_header(args[:height]) }
+      end
+
+      # Returns the network this wallet is configured for.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { network: String } 'mainnet' or 'testnet'
+      def get_network(_args = {}, _originator: nil)
+        { network: @network }
+      end
+
+      # Returns the wallet version string.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { version: String } in vendor-major.minor.patch format
+      def get_version(_args = {}, _originator: nil)
+        { version: "bsv-wallet-#{BSV::WalletInterface::VERSION}" }
+      end
+
+      # --- Authentication ---
+
+      # Checks whether the user is authenticated.
+      # For local wallets with a private key, this is always true.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { authenticated: Boolean }
+      def is_authenticated(_args = {}, _originator: nil)
+        { authenticated: true }
+      end
+
+      # Waits until the user is authenticated.
+      # For local wallets, returns immediately.
+      #
+      # @param _args [Hash] unused (empty hash)
+      # @return [Hash] { authenticated: true }
+      def wait_for_authentication(_args = {}, _originator: nil)
+        { authenticated: true }
+      end
+
+      # --- Identity and Certificate Management ---
+
+      # Acquires an identity certificate via direct storage.
+      #
+      # The 'issuance' protocol (which requires HTTP to a certifier URL) is
+      # not yet supported and raises {UnsupportedActionError}.
+      #
+      # @param args [Hash]
+      # @option args [String] :type certificate type (base64)
+      # @option args [String] :certifier certifier public key hex
+      # @option args [String] :acquisition_protocol 'direct' or 'issuance'
+      # @option args [Hash] :fields certificate fields (field_name => value)
+      # @option args [String] :serial_number serial number (required for direct)
+      # @option args [String] :revocation_outpoint outpoint string (required for direct)
+      # @option args [String] :signature certifier signature hex (required for direct)
+      # @option args [String] :keyring_revealer pubkey hex or 'certifier' (required for direct)
+      # @option args [Hash] :keyring_for_subject field_name => base64 key (required for direct)
+      # @return [Hash] the stored certificate
+      def acquire_certificate(args, _originator: nil)
+        validate_acquire_certificate!(args)
+
+        raise UnsupportedActionError, 'acquire_certificate with issuance protocol' if args[:acquisition_protocol] == 'issuance'
+
+        cert = {
+          type: args[:type],
+          subject: @key_deriver.identity_key,
+          serial_number: args[:serial_number],
+          certifier: args[:certifier],
+          revocation_outpoint: args[:revocation_outpoint],
+          signature: args[:signature],
+          fields: args[:fields],
+          keyring: args[:keyring_for_subject]
+        }
+
+        @storage.store_certificate(cert)
+        cert_without_keyring(cert)
+      end
+
+      # Lists identity certificates filtered by certifier and type.
+      #
+      # @param args [Hash]
+      # @option args [Array<String>] :certifiers certifier public keys
+      # @option args [Array<String>] :types certificate types
+      # @option args [Integer] :limit max results (default 10)
+      # @option args [Integer] :offset number to skip (default 0)
+      # @return [Hash] { total_certificates:, certificates: [...] }
+      def list_certificates(args, _originator: nil)
+        raise InvalidParameterError.new('certifiers', 'a non-empty Array') unless args[:certifiers].is_a?(Array) && !args[:certifiers].empty?
+        raise InvalidParameterError.new('types', 'a non-empty Array') unless args[:types].is_a?(Array) && !args[:types].empty?
+
+        query = {
+          certifiers: args[:certifiers],
+          types: args[:types],
+          limit: args[:limit] || 10,
+          offset: args[:offset] || 0
+        }
+        total = @storage.count_certificates(query)
+        certs = @storage.find_certificates(query)
+        { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
+      end
+
+      # Proves select fields of an identity certificate to a verifier.
+      #
+      # Encrypts each requested field's keyring entry for the verifier using
+      # protocol-derived encryption (BRC-2), allowing the verifier to decrypt
+      # only the revealed fields.
+      #
+      # @param args [Hash]
+      # @option args [Hash] :certificate the certificate to prove
+      # @option args [Array<String>] :fields_to_reveal field names to reveal
+      # @option args [String] :verifier verifier public key hex
+      # @return [Hash] { keyring_for_verifier: { field_name => Array<Integer> } }
+      def prove_certificate(args, _originator: nil)
+        cert_arg = args[:certificate]
+        fields_to_reveal = args[:fields_to_reveal]
+        verifier = args[:verifier]
+
+        raise InvalidParameterError.new('certificate', 'a Hash') unless cert_arg.is_a?(Hash)
+        raise InvalidParameterError.new('fields_to_reveal', 'a non-empty Array') unless fields_to_reveal.is_a?(Array) && !fields_to_reveal.empty?
+
+        Validators.validate_pub_key_hex!(verifier, 'verifier')
+
+        # Look up the full certificate (with keyring) from storage
+        stored = find_stored_certificate(cert_arg)
+        raise WalletError, 'Certificate not found in wallet' unless stored
+        raise WalletError, 'Certificate has no keyring' unless stored[:keyring]
+
+        keyring_for_verifier = {}
+        fields_to_reveal.each do |field_name|
+          key_value = stored[:keyring][field_name] || stored[:keyring][field_name.to_sym]
+          raise WalletError, "Keyring entry not found for field '#{field_name}'" unless key_value
+
+          # Encrypt the keyring entry for the verifier
+          encrypted = encrypt({
+                                plaintext: key_value.bytes,
+                                protocol_id: [2, 'certificate field revelation'],
+                                key_id: "#{cert_arg[:type]} #{cert_arg[:serial_number]} #{field_name}",
+                                counterparty: verifier
+                              })
+          keyring_for_verifier[field_name] = encrypted[:ciphertext]
+        end
+
+        { keyring_for_verifier: keyring_for_verifier }
+      end
+
+      # Removes a certificate from the wallet.
+      #
+      # @param args [Hash]
+      # @option args [String] :type certificate type
+      # @option args [String] :serial_number serial number
+      # @option args [String] :certifier certifier public key hex
+      # @return [Hash] { relinquished: true }
+      def relinquish_certificate(args, _originator: nil)
+        deleted = @storage.delete_certificate(
+          type: args[:type],
+          serial_number: args[:serial_number],
+          certifier: args[:certifier]
+        )
+        raise WalletError, 'Certificate not found' unless deleted
+
+        { relinquished: true }
+      end
+
+      # Discovers certificates issued to a given identity key.
+      #
+      # For a local wallet, searches stored certificates where the subject
+      # matches the given identity key.
+      #
+      # @param args [Hash]
+      # @option args [String] :identity_key public key hex to search
+      # @option args [Integer] :limit max results (default 10)
+      # @option args [Integer] :offset number to skip (default 0)
+      # @return [Hash] { total_certificates:, certificates: [...] }
+      def discover_by_identity_key(args, _originator: nil)
+        Validators.validate_pub_key_hex!(args[:identity_key], 'identity_key')
+
+        query = { subject: args[:identity_key], limit: args[:limit] || 10, offset: args[:offset] || 0 }
+        total = @storage.count_certificates(query)
+        certs = @storage.find_certificates(query)
+        { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
+      end
+
+      # Discovers certificates matching specific attribute values.
+      #
+      # Searches stored certificates where field values match the given
+      # attributes. Only searches certificates belonging to this wallet.
+      #
+      # @param args [Hash]
+      # @option args [Hash] :attributes field_name => value pairs to match
+      # @option args [Integer] :limit max results (default 10)
+      # @option args [Integer] :offset number to skip (default 0)
+      # @return [Hash] { total_certificates:, certificates: [...] }
+      def discover_by_attributes(args, _originator: nil)
+        raise InvalidParameterError.new('attributes', 'a non-empty Hash') unless args[:attributes].is_a?(Hash) && !args[:attributes].empty?
+
+        query = { attributes: args[:attributes], limit: args[:limit] || 10, offset: args[:offset] || 0 }
+        total = @storage.count_certificates(query)
+        certs = @storage.find_certificates(query)
+        { total_certificates: total, certificates: certs.map { |c| cert_without_keyring(c) } }
+      end
+
       private
 
       # --- Validation ---
@@ -481,6 +709,40 @@ module BSV
                                 spendable: true
                               })
       end
+
+      # --- Certificate helpers ---
+
+      def validate_acquire_certificate!(args)
+        raise InvalidParameterError.new('type', 'a String') unless args[:type].is_a?(String)
+
+        Validators.validate_pub_key_hex!(args[:certifier], 'certifier')
+        raise InvalidParameterError.new('fields', 'a Hash') unless args[:fields].is_a?(Hash)
+
+        protocol = args[:acquisition_protocol]
+        raise InvalidParameterError.new('acquisition_protocol', '"direct" or "issuance"') unless %w[direct issuance].include?(protocol)
+
+        return unless protocol == 'direct'
+
+        raise InvalidParameterError.new('serial_number', 'present for direct acquisition') unless args[:serial_number]
+        raise InvalidParameterError.new('revocation_outpoint', 'present for direct acquisition') unless args[:revocation_outpoint]
+        raise InvalidParameterError.new('signature', 'present for direct acquisition') unless args[:signature]
+        raise InvalidParameterError.new('keyring_for_subject', 'a Hash for direct acquisition') unless args[:keyring_for_subject].is_a?(Hash)
+      end
+
+      def find_stored_certificate(cert_arg)
+        results = @storage.find_certificates({
+                                               certifiers: [cert_arg[:certifier]],
+                                               types: [cert_arg[:type]],
+                                               limit: 10_000
+                                             })
+        results.find { |c| c[:serial_number] == cert_arg[:serial_number] }
+      end
+
+      def cert_without_keyring(cert)
+        result = cert.dup
+        result.delete(:keyring)
+        result
+      end
     end
   end
 end

data/lib/bsv/wallet_interface.rb

@@ -11,9 +11,11 @@ module BSV
     autoload :KeyDeriver,       'bsv/wallet_interface/key_deriver'
     autoload :ProtoWallet,      'bsv/wallet_interface/proto_wallet'
     autoload :Validators,       'bsv/wallet_interface/validators'
-    autoload :StorageAdapter,   'bsv/wallet_interface/storage_adapter'
-    autoload :MemoryStore,      'bsv/wallet_interface/memory_store'
-    autoload :WalletClient,     'bsv/wallet_interface/wallet_client'
+    autoload :StorageAdapter,    'bsv/wallet_interface/storage_adapter'
+    autoload :MemoryStore,       'bsv/wallet_interface/memory_store'
+    autoload :ChainProvider,     'bsv/wallet_interface/chain_provider'
+    autoload :NullChainProvider, 'bsv/wallet_interface/null_chain_provider'
+    autoload :WalletClient,      'bsv/wallet_interface/wallet_client'
 
     # Error classes
     autoload :WalletError,            'bsv/wallet_interface/errors/wallet_error'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Simon Bettison
@@ -91,6 +91,7 @@ files:
 - lib/bsv/wallet/insufficient_funds_error.rb
 - lib/bsv/wallet/wallet.rb
 - lib/bsv/wallet_interface.rb
+- lib/bsv/wallet_interface/chain_provider.rb
 - lib/bsv/wallet_interface/errors/invalid_hmac_error.rb
 - lib/bsv/wallet_interface/errors/invalid_parameter_error.rb
 - lib/bsv/wallet_interface/errors/invalid_signature_error.rb
@@ -99,6 +100,7 @@ files:
 - lib/bsv/wallet_interface/interface.rb
 - lib/bsv/wallet_interface/key_deriver.rb
 - lib/bsv/wallet_interface/memory_store.rb
+- lib/bsv/wallet_interface/null_chain_provider.rb
 - lib/bsv/wallet_interface/proto_wallet.rb
 - lib/bsv/wallet_interface/storage_adapter.rb
 - lib/bsv/wallet_interface/validators.rb