bsv-sdk 0.15.0 → 0.17.0

data/lib/bsv/wallet/interface/brc100.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # BRC-100 abstract wallet interface — all 28 methods.
+    #
+    # Include this module and override the methods your implementation supports.
+    # Unimplemented methods raise +NotImplementedError+.
+    #
+    # The 28 methods are grouped into six functional areas matching
+    # the BRC-100 Interface Structure specification.
+    #
+    # @example
+    #   class MyWallet
+    #     include BSV::Wallet::Interface::BRC100
+    #
+    #     def get_height(originator: nil)
+    #       { height: 800_000 }
+    #     end
+    #   end
+    module Interface
+      module BRC100
+        # --- Transaction Operations (codes 1-7) ---
+
+        # Creates a new Bitcoin transaction.
+        #
+        # @param description [String] human-readable description (5-50 chars)
+        # @param inputs [Array<Hash>] optional inputs to consume
+        #   - :outpoint [String] txid.index being consumed
+        #   - :unlocking_script [String] hex unlocking script
+        #   - :unlocking_script_length [Integer] length, if script provided later via {#sign_action}
+        #   - :input_description [String] what this input consumes (5-50 chars)
+        #   - :sequence_number [Integer] optional sequence number
+        # @param outputs [Array<Hash>] optional outputs to create
+        #   - :locking_script [String] hex locking script
+        #   - :satoshis [Integer] output value
+        #   - :output_description [String] what this output represents (5-50 chars)
+        #   - :basket [String] optional basket name for UTXO tracking
+        #   - :custom_instructions [String] application-specific context
+        #   - :tags [Array<String>] output tags for filtering
+        # @return [Hash] BRC-100 spec-mandated keys: :txid (display-order hex), :tx, :no_send_change,
+        #   :send_with_results, :signable_transaction
+        def create_action(description:, input_beef: nil, inputs: nil, outputs: nil,
+                          lock_time: nil, version: nil, labels: nil,
+                          sign_and_process: true, accept_delayed_broadcast: true,
+                          # BRC-100 spec-mandated parameter names — display-order hex txids
+                          trust_self: nil, known_txids: nil, return_txid_only: false,
+                          no_send: false, no_send_change: nil, send_with: nil,
+                          randomize_outputs: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Signs a transaction previously created with {#create_action}.
+        #
+        # @param spends [Hash{Integer => Hash}] input index => { unlocking_script:, sequence_number: }
+        # @param reference [String] reference returned by {#create_action}
+        def sign_action(spends:, reference:,
+                        accept_delayed_broadcast: true,
+                        return_txid_only: false, # BRC-100 spec-mandated parameter name
+                        no_send: false, send_with: nil, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Aborts a transaction that has not yet been finalized.
+        def abort_action(reference:, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Lists transactions matching the specified labels.
+        #
+        # @return [Hash] :total_actions, :actions
+        def list_actions(labels:, label_query_mode: :any,
+                         include_labels: false, include_inputs: false,
+                         include_input_source_locking_scripts: false,
+                         include_input_unlocking_scripts: false,
+                         include_outputs: false, include_output_locking_scripts: false,
+                         limit: 10, offset: 0, seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Internalizes a transaction — labels it, pays outputs to the wallet balance,
+        # inserts outputs into baskets, and/or tags them.
+        #
+        # @param tx [Array<Integer>] Atomic BEEF-formatted transaction (byte array)
+        # @param outputs [Array<Hash>] metadata per output
+        #   - :output_index [Integer] index within the transaction
+        #   - :protocol [Symbol] :wallet_payment or :basket_insertion
+        #   - :payment_remittance [Hash] for payments: { derivation_prefix:, derivation_suffix:, sender_identity_key: }
+        #   - :insertion_remittance [Hash] for insertions: { basket:, custom_instructions:, tags: }
+        def internalize_action(tx:, outputs:, description:, labels: nil,
+                               seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Lists spendable outputs in a basket.
+        #
+        # @param include [Symbol] nil, :locking_scripts, or :entire_transactions
+        # @return [Hash] :total_outputs, :beef, :outputs
+        def list_outputs(basket:, tags: nil, tag_query_mode: :any, include: nil,
+                         include_custom_instructions: false, include_tags: false,
+                         include_labels: false, limit: 10, offset: 0,
+                         seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Removes an output from a basket without spending it.
+        def relinquish_output(basket:, output:, originator: nil)
+          raise NotImplementedError
+        end
+
+        # --- Public Key Management (codes 8-10) ---
+
+        # Retrieves a derived or identity public key.
+        #
+        # @param protocol_id [Array(Integer, String)] security level (0-2) and protocol string
+        # @param counterparty [String] public key hex, 'self', or 'anyone'
+        # @return [Hash] :public_key
+        def get_public_key(identity_key: false, protocol_id: nil, key_id: nil,
+                           privileged: false, privileged_reason: nil,
+                           counterparty: nil, for_self: false,
+                           seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Reveals key linkage with a counterparty to a verifier, across all interactions.
+        def reveal_counterparty_key_linkage(counterparty:, verifier:,
+                                            privileged: false, privileged_reason: nil,
+                                            originator: nil)
+          raise NotImplementedError
+        end
+
+        # Reveals key linkage for a specific protocol and key interaction.
+        def reveal_specific_key_linkage(counterparty:, verifier:, protocol_id:, key_id:,
+                                        privileged: false, privileged_reason: nil,
+                                        originator: nil)
+          raise NotImplementedError
+        end
+
+        # --- Cryptography Operations (codes 11-16) ---
+
+        # Encrypts plaintext using derived keys.
+        def encrypt(plaintext:, protocol_id:, key_id:,
+                    privileged: false, privileged_reason: nil,
+                    counterparty: nil, seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Decrypts ciphertext using derived keys.
+        def decrypt(ciphertext:, protocol_id:, key_id:,
+                    privileged: false, privileged_reason: nil,
+                    counterparty: nil, seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Creates an HMAC for the provided data.
+        def create_hmac(data:, protocol_id:, key_id:,
+                        privileged: false, privileged_reason: nil,
+                        counterparty: nil, seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Verifies an HMAC against the provided data.
+        def verify_hmac(data:, hmac:, protocol_id:, key_id:,
+                        privileged: false, privileged_reason: nil,
+                        counterparty: nil, seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Creates a digital signature (ECDSA) for data or a pre-computed hash.
+        def create_signature(protocol_id:, key_id:, data: nil, hash_to_directly_sign: nil,
+                             privileged: false, privileged_reason: nil,
+                             counterparty: nil, seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Verifies a digital signature against data or a pre-computed hash.
+        def verify_signature(signature:, protocol_id:, key_id:, data: nil,
+                             hash_to_directly_verify: nil,
+                             privileged: false, privileged_reason: nil,
+                             counterparty: nil, for_self: false,
+                             seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # --- Identity and Certificate Management (codes 17-22) ---
+
+        # Acquires an identity certificate from a certifier or by direct receipt.
+        #
+        # @param acquisition_protocol [Symbol] :direct or :issuance
+        # @param fields [Hash{String => String}] certificate field names to values
+        def acquire_certificate(type:, certifier:, acquisition_protocol:, fields:,
+                                serial_number: nil, revocation_outpoint: nil,
+                                signature: nil, certifier_url: nil,
+                                keyring_revealer: nil, keyring_for_subject: nil,
+                                privileged: false, privileged_reason: nil, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Lists identity certificates filtered by certifier(s) and type(s).
+        def list_certificates(certifiers:, types:, limit: 10, offset: 0,
+                              privileged: false, privileged_reason: nil, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Proves select fields of a certificate to a verifier.
+        #
+        # @param certificate [Hash] the full certificate (type, subject, serial_number,
+        #   certifier, revocation_outpoint, signature, fields)
+        # @param fields_to_reveal [Array<String>] field names to disclose
+        def prove_certificate(certificate:, fields_to_reveal:, verifier:,
+                              privileged: false, privileged_reason: nil, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Removes a certificate from the wallet.
+        def relinquish_certificate(type:, serial_number:, certifier:, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Discovers certificates issued to a given identity key.
+        def discover_by_identity_key(identity_key:, limit: 10, offset: 0,
+                                     seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Discovers certificates matching specific attribute values.
+        #
+        # @param attributes [Hash{String => String}] field name/value pairs to match
+        def discover_by_attributes(attributes:, limit: 10, offset: 0,
+                                   seek_permission: true, originator: nil)
+          raise NotImplementedError
+        end
+
+        # --- Authentication (codes 23-24) ---
+
+        # Checks whether the user is authenticated.
+        def authenticated?(originator: nil)
+          raise NotImplementedError
+        end
+
+        # Blocks until the user is authenticated.
+        def wait_for_authentication(originator: nil)
+          raise NotImplementedError
+        end
+
+        # --- Blockchain and Network Data (codes 25-28) ---
+
+        # Returns the current blockchain height.
+        def get_height(originator: nil)
+          raise NotImplementedError
+        end
+
+        # Returns the 80-byte block header at the given height.
+        def get_header_for_height(height:, originator: nil)
+          raise NotImplementedError
+        end
+
+        # Returns the network (:mainnet or :testnet).
+        def get_network(originator: nil)
+          raise NotImplementedError
+        end
+
+        # Returns the wallet version string.
+        def get_version(originator: nil)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/interface.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Interface
+      autoload :BRC100, 'bsv/wallet/interface/brc100'
+    end
+  end
+end

data/lib/bsv/wallet/proto_wallet/key_deriver.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Wallet
+    class ProtoWallet
+      # BRC-42/43 key derivation.
+      #
+      # Derives child keys from a root private key using BKDS (BSV Key Derivation
+      # Scheme). Supports protocol IDs, key IDs, counterparties, and security
+      # levels as defined in BRC-43.
+      class KeyDeriver
+        include Validators
+
+        ANYONE_BN = OpenSSL::BN.new(1)
+
+        attr_reader :root_key
+
+        # @param root_key [BSV::Primitives::PrivateKey, String] a private key or 'anyone'
+        def initialize(root_key)
+          @root_key = if root_key == 'anyone'
+                        BSV::Primitives::PrivateKey.new(ANYONE_BN)
+                      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
+
+        # Returns the identity public key as a hex string.
+        # @return [String] 66-character compressed public key hex
+        def identity_key
+          @identity_key ||= @root_key.public_key.to_hex
+        end
+
+        # Derives a public key using BRC-42 key derivation.
+        #
+        # @param protocol_id [Array] [security_level, protocol_name]
+        # @param key_id [String] key identifier
+        # @param counterparty [String] public key hex, 'self', or 'anyone'
+        # @param for_self [Boolean] derive from own identity rather than counterparty's
+        # @return [BSV::Primitives::PublicKey]
+        def derive_public_key(protocol_id, key_id, counterparty, for_self: false)
+          Validators.validate_protocol_id!(protocol_id)
+          Validators.validate_key_id!(key_id)
+          invoice = compute_invoice_number(protocol_id, key_id)
+          BSV.logger&.debug { "[KeyDeriver] derive_public_key: invoice=#{invoice.inspect} for_self=#{for_self}" }
+          counterparty_pub = resolve_counterparty(counterparty)
+
+          if for_self
+            @root_key.derive_child(counterparty_pub, invoice).public_key
+          else
+            counterparty_pub.derive_child(@root_key, invoice)
+          end
+        end
+
+        # Derives a private key using BRC-42 key derivation.
+        #
+        # @param protocol_id [Array] [security_level, protocol_name]
+        # @param key_id [String] key identifier
+        # @param counterparty [String] public key hex, 'self', or 'anyone'
+        # @return [BSV::Primitives::PrivateKey]
+        def derive_private_key(protocol_id, key_id, counterparty)
+          Validators.validate_protocol_id!(protocol_id)
+          Validators.validate_key_id!(key_id)
+          invoice = compute_invoice_number(protocol_id, key_id)
+          BSV.logger&.debug { "[KeyDeriver] derive_private_key: invoice=#{invoice.inspect}" }
+          counterparty_pub = resolve_counterparty(counterparty)
+          @root_key.derive_child(counterparty_pub, invoice)
+        end
+
+        # Derives a symmetric key for encryption/HMAC operations.
+        #
+        # Uses ECDH between the derived private and public child keys to
+        # produce a shared secret, then uses the X-coordinate as the key.
+        #
+        # @param protocol_id [Array] [security_level, protocol_name]
+        # @param key_id [String] key identifier
+        # @param counterparty [String] public key hex, 'self', or 'anyone'
+        # @return [BSV::Primitives::SymmetricKey]
+        def derive_symmetric_key(protocol_id, key_id, counterparty)
+          Validators.validate_protocol_id!(protocol_id)
+          Validators.validate_key_id!(key_id)
+          invoice = compute_invoice_number(protocol_id, key_id)
+          counterparty_pub = resolve_counterparty(counterparty)
+
+          derived_private = @root_key.derive_child(counterparty_pub, invoice)
+          derived_public  = counterparty_pub.derive_child(@root_key, invoice)
+
+          BSV::Primitives::SymmetricKey.from_ecdh(derived_private, derived_public)
+        end
+
+        # Reveals the ECDH shared secret between this wallet and a counterparty.
+        # Used for BRC-69 Method 1 (counterparty key linkage).
+        #
+        # @param counterparty [String] public key hex (not 'self')
+        # @return [String] compressed shared secret bytes
+        def reveal_counterparty_secret(counterparty)
+          raise InvalidParameterError.new('counterparty', 'not "self" for key linkage revelation') if counterparty == 'self'
+
+          counterparty_pub = resolve_counterparty(counterparty)
+          @root_key.derive_shared_secret(counterparty_pub).compressed
+        end
+
+        # Reveals the specific key offset for a particular derived key.
+        # Used for BRC-69 Method 2 (specific key linkage).
+        #
+        # @param counterparty [String] public key hex
+        # @param protocol_id [Array] [security_level, protocol_name]
+        # @param key_id [String] key identifier
+        # @return [String] HMAC-SHA256 bytes (the key offset)
+        def reveal_specific_secret(counterparty, protocol_id, key_id)
+          Validators.validate_protocol_id!(protocol_id)
+          Validators.validate_key_id!(key_id)
+          counterparty_pub = resolve_counterparty(counterparty)
+          shared  = @root_key.derive_shared_secret(counterparty_pub)
+          invoice = compute_invoice_number(protocol_id, key_id)
+          BSV::Primitives::Digest.hmac_sha256(shared.compressed, invoice.encode('UTF-8'))
+        end
+
+        private
+
+        # Resolves a counterparty identifier to a PublicKey.
+        #
+        # @param counterparty [String] 'self', 'anyone', or a hex public key
+        # @return [BSV::Primitives::PublicKey]
+        def resolve_counterparty(counterparty)
+          case counterparty
+          when 'self'
+            @root_key.public_key
+          when 'anyone'
+            BSV::Primitives::PrivateKey.new(ANYONE_BN).public_key
+          else
+            Validators.validate_counterparty!(counterparty)
+            BSV::Primitives::PublicKey.from_hex(counterparty)
+          end
+        end
+
+        # Computes the invoice number from a protocol ID and key ID.
+        # Format: "#{security_level}-#{protocol_name}-#{key_id}"
+        #
+        # @param protocol_id [Array] [security_level, protocol_name]
+        # @param key_id [String]
+        # @return [String]
+        def compute_invoice_number(protocol_id, key_id)
+          "#{protocol_id[0]}-#{protocol_id[1].downcase.strip}-#{key_id}"
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/proto_wallet/validators.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class ProtoWallet
+      # Validation helpers for BRC-100 wallet method parameters.
+      #
+      # Provides the subset of validators required by KeyDeriver and ProtoWallet.
+      # Raises +InvalidParameterError+ for any invalid input.
+      module Validators
+        module_function
+
+        # Validates a BRC-43 protocol ID.
+        #
+        # Must be an Array of [Integer(0-2), String(5-400 chars)]. The name is
+        # normalized (stripped and downcased) before length/content checks.
+        #
+        # @param protocol_id [Object] the value to validate
+        # @raise [InvalidParameterError]
+        def validate_protocol_id!(protocol_id)
+          unless protocol_id.is_a?(Array) && protocol_id.length == 2
+            raise InvalidParameterError.new('protocol_id', 'an Array of [security_level, protocol_name]')
+          end
+
+          level, name = protocol_id
+          raise InvalidParameterError.new('protocol_id security level', '0, 1, or 2') unless [0, 1, 2].include?(level)
+          raise InvalidParameterError.new('protocol_id name', 'a String') unless name.is_a?(String)
+
+          name = name.strip.downcase
+          max_length = name.start_with?('specific linkage revelation') ? 430 : 400
+          raise InvalidParameterError.new('protocol_id name', "between 5 and #{max_length} characters") if name.length < 5 || name.length > max_length
+
+          raise InvalidParameterError.new('protocol_id name', 'lowercase letters, numbers, and spaces only') unless name.match?(/\A[a-z0-9 ]+\z/)
+
+          raise InvalidParameterError.new('protocol_id name', 'free of consecutive spaces') if name.include?('  ')
+        end
+
+        # Validates a BRC-43 key ID.
+        #
+        # Must be a non-empty String of at most 800 bytes.
+        #
+        # @param key_id [Object] the value to validate
+        # @raise [InvalidParameterError]
+        def validate_key_id!(key_id)
+          raise InvalidParameterError.new('key_id', 'a String') unless key_id.is_a?(String)
+
+          byte_length = key_id.bytesize
+          raise InvalidParameterError.new('key_id', 'between 1 and 800 bytes') if byte_length < 1 || byte_length > 800
+        end
+
+        # Validates a counterparty: 'self', 'anyone', or a 66-char hex pubkey.
+        #
+        # @param counterparty [Object] the value to validate
+        # @raise [InvalidParameterError]
+        def validate_counterparty!(counterparty)
+          return if %w[self anyone].include?(counterparty)
+
+          validate_pub_key_hex!(counterparty, 'counterparty')
+        end
+
+        # Validates a compressed public key in hex form (66 chars, 02/03/04 prefix).
+        #
+        # @param value [Object] the value to validate
+        # @param name [String] parameter name for error messages
+        # @raise [InvalidParameterError]
+        def validate_pub_key_hex!(value, name = 'public_key')
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          raise InvalidParameterError.new(name, 'a 66-character hex string (compressed public key)') unless value.match?(/\A[0-9a-f]{66}\z/)
+        end
+      end
+    end
+  end
+end