bsv-sdk 0.2.1 → 0.3.0

data/lib/bsv/wallet_interface/interface.rb

@@ -0,0 +1,384 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # BRC-100 Wallet Interface
+    #
+    # Defines the 28 methods of the standard BSV wallet-to-application interface.
+    # Include this module and override the methods your implementation supports.
+    # Unimplemented methods raise {UnsupportedActionError}.
+    module Interface
+      # rubocop:disable Lint/UnusedMethodArgument
+
+      # --- Transaction Operations ---
+
+      # Creates a new Bitcoin transaction with metadata and labels.
+      #
+      # @param args [Hash] transaction parameters
+      # @option args [String] :description (required) 5-50 char description
+      # @option args [Array<Integer>] :input_beef BEEF data for inputs
+      # @option args [Array<Hash>] :inputs input objects with :outpoint, :unlocking_script, :input_description
+      # @option args [Array<Hash>] :outputs output objects with :locking_script, :satoshis, :output_description
+      # @option args [Integer] :lock_time optional lock time
+      # @option args [Integer] :version optional transaction version
+      # @option args [Array<String>] :labels optional transaction labels
+      # @option args [Hash] :options optional processing options
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :txid, :tx, :no_send_change, :send_with_results, :signable_transaction
+      def create_action(args, originator: nil)
+        raise UnsupportedActionError, 'create_action'
+      end
+
+      # Signs a previously created transaction.
+      #
+      # @param args [Hash] signing parameters
+      # @option args [Hash] :spends map of input indexes to unlocking scripts
+      # @option args [String] :reference base64 reference from create_action
+      # @option args [Hash] :options optional processing options
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :txid, :tx, :send_with_results
+      def sign_action(args, originator: nil)
+        raise UnsupportedActionError, 'sign_action'
+      end
+
+      # Aborts an incomplete transaction.
+      #
+      # @param args [Hash]
+      # @option args [String] :reference base64 reference to abort
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { aborted: true }
+      def abort_action(args, originator: nil)
+        raise UnsupportedActionError, 'abort_action'
+      end
+
+      # Lists transactions matching the specified labels.
+      #
+      # @param args [Hash] query parameters
+      # @option args [Array<String>] :labels (required) labels to filter by
+      # @option args [String] :label_query_mode 'any' or 'all'
+      # @option args [Boolean] :include_labels include labels in results
+      # @option args [Boolean] :include_inputs include input details
+      # @option args [Boolean] :include_outputs include output details
+      # @option args [Integer] :limit max results (default 10, max 10000)
+      # @option args [Integer] :offset number to skip
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :total_actions, :actions
+      def list_actions(args, originator: nil)
+        raise UnsupportedActionError, 'list_actions'
+      end
+
+      # Accepts an incoming transaction for internalization.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :tx Atomic BEEF-formatted transaction
+      # @option args [Array<Hash>] :outputs metadata about outputs
+      # @option args [String] :description 5-50 char description
+      # @option args [Array<String>] :labels optional labels
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { accepted: true }
+      def internalize_action(args, originator: nil)
+        raise UnsupportedActionError, 'internalize_action'
+      end
+
+      # Lists spendable outputs in a basket.
+      #
+      # @param args [Hash]
+      # @option args [String] :basket (required) basket name
+      # @option args [Array<String>] :tags optional tag filter
+      # @option args [String] :tag_query_mode 'any' or 'all'
+      # @option args [String] :include 'locking scripts' or 'entire transactions'
+      # @option args [Integer] :limit max results
+      # @option args [Integer] :offset number to skip
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :total_outputs, :outputs
+      def list_outputs(args, originator: nil)
+        raise UnsupportedActionError, 'list_outputs'
+      end
+
+      # Releases an output from basket tracking.
+      #
+      # @param args [Hash]
+      # @option args [String] :basket basket name
+      # @option args [String] :output outpoint string
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { relinquished: true }
+      def relinquish_output(args, originator: nil)
+        raise UnsupportedActionError, 'relinquish_output'
+      end
+
+      # --- Public Key Management ---
+
+      # Retrieves a derived or identity public key.
+      #
+      # @param args [Hash]
+      # @option args [Boolean] :identity_key if true, return the identity key
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :for_self derive from own identity
+      # @option args [Boolean] :privileged privileged mode
+      # @option args [String] :privileged_reason reason for privileged access
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { public_key: String }
+      def get_public_key(args, originator: nil)
+        raise UnsupportedActionError, 'get_public_key'
+      end
+
+      # Reveals key linkage between self and a counterparty to a verifier.
+      #
+      # @param args [Hash]
+      # @option args [String] :counterparty counterparty public key hex
+      # @option args [String] :verifier verifier public key hex
+      # @option args [Boolean] :privileged privileged mode
+      # @option args [String] :privileged_reason reason for privileged access
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :prover, :verifier, :counterparty, :revelation_time, :encrypted_linkage, :encrypted_linkage_proof
+      def reveal_counterparty_key_linkage(args, originator: nil)
+        raise UnsupportedActionError, 'reveal_counterparty_key_linkage'
+      end
+
+      # Reveals specific key linkage for a particular interaction.
+      #
+      # @param args [Hash]
+      # @option args [String] :counterparty counterparty public key hex
+      # @option args [String] :verifier verifier public key hex
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [Boolean] :privileged privileged mode
+      # @option args [String] :privileged_reason reason for privileged access
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :prover, :verifier, :counterparty, :protocol_id, :key_id, :encrypted_linkage, :encrypted_linkage_proof, :proof_type
+      def reveal_specific_key_linkage(args, originator: nil)
+        raise UnsupportedActionError, 'reveal_specific_key_linkage'
+      end
+
+      # --- Cryptography Operations ---
+
+      # Encrypts data using a derived symmetric key.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :plaintext byte array to encrypt
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :privileged privileged mode
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { ciphertext: Array<Integer> }
+      def encrypt(args, originator: nil)
+        raise UnsupportedActionError, 'encrypt'
+      end
+
+      # Decrypts data using a derived symmetric key.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :ciphertext byte array to decrypt
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :privileged privileged mode
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { plaintext: Array<Integer> }
+      def decrypt(args, originator: nil)
+        raise UnsupportedActionError, 'decrypt'
+      end
+
+      # Creates an HMAC using a derived symmetric key.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :data byte array
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :privileged privileged mode
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { hmac: Array<Integer> }
+      def create_hmac(args, originator: nil)
+        raise UnsupportedActionError, 'create_hmac'
+      end
+
+      # Verifies an HMAC using a derived symmetric key.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :data byte array
+      # @option args [Array<Integer>] :hmac HMAC to verify
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :privileged privileged mode
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { valid: true }
+      def verify_hmac(args, originator: nil)
+        raise UnsupportedActionError, 'verify_hmac'
+      end
+
+      # Creates a digital signature using a derived private key.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :data data to sign
+      # @option args [Array<Integer>] :hash_to_directly_sign pre-hashed data to sign
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :privileged privileged mode
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { signature: Array<Integer> }
+      def create_signature(args, originator: nil)
+        raise UnsupportedActionError, 'create_signature'
+      end
+
+      # Verifies a digital signature using a derived public key.
+      #
+      # @param args [Hash]
+      # @option args [Array<Integer>] :data original data
+      # @option args [Array<Integer>] :hash_to_directly_verify pre-hashed data
+      # @option args [Array<Integer>] :signature DER-encoded signature
+      # @option args [Array] :protocol_id [security_level, protocol_name]
+      # @option args [String] :key_id key identifier
+      # @option args [String] :counterparty public key hex, 'self', or 'anyone'
+      # @option args [Boolean] :for_self verify own signature
+      # @option args [Boolean] :privileged privileged mode
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { valid: true }
+      def verify_signature(args, originator: nil)
+        raise UnsupportedActionError, 'verify_signature'
+      end
+
+      # --- Identity and Certificate Management ---
+
+      # Acquires an identity certificate.
+      #
+      # @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
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] certificate data
+      def acquire_certificate(args, originator: nil)
+        raise UnsupportedActionError, 'acquire_certificate'
+      end
+
+      # Lists identity certificates.
+      #
+      # @param args [Hash]
+      # @option args [Array<String>] :certifiers certifier public keys
+      # @option args [Array<String>] :types certificate types
+      # @option args [Integer] :limit max results
+      # @option args [Integer] :offset number to skip
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :total_certificates, :certificates
+      def list_certificates(args, originator: nil)
+        raise UnsupportedActionError, 'list_certificates'
+      end
+
+      # Proves select fields of a certificate to a verifier.
+      #
+      # @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
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { keyring_for_verifier: Hash }
+      def prove_certificate(args, originator: nil)
+        raise UnsupportedActionError, 'prove_certificate'
+      end
+
+      # Removes a certificate from the wallet.
+      #
+      # @param args [Hash]
+      # @option args [String] :type certificate type
+      # @option args [String] :serial_number certificate serial number
+      # @option args [String] :certifier certifier public key hex
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { relinquished: true }
+      def relinquish_certificate(args, originator: nil)
+        raise UnsupportedActionError, 'relinquish_certificate'
+      end
+
+      # Discovers certificates by identity key.
+      #
+      # @param args [Hash]
+      # @option args [String] :identity_key public key hex to search
+      # @option args [Integer] :limit max results
+      # @option args [Integer] :offset number to skip
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :total_certificates, :certificates
+      def discover_by_identity_key(args, originator: nil)
+        raise UnsupportedActionError, 'discover_by_identity_key'
+      end
+
+      # Discovers certificates by attributes.
+      #
+      # @param args [Hash]
+      # @option args [Hash] :attributes attribute name/value pairs to match
+      # @option args [Integer] :limit max results
+      # @option args [Integer] :offset number to skip
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] with :total_certificates, :certificates
+      def discover_by_attributes(args, originator: nil)
+        raise UnsupportedActionError, 'discover_by_attributes'
+      end
+
+      # --- Blockchain and Network Data ---
+
+      # Returns the current blockchain height.
+      #
+      # @param args [Hash] empty hash
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { height: Integer }
+      def get_height(args = {}, originator: nil)
+        raise UnsupportedActionError, 'get_height'
+      end
+
+      # Returns the block header at a given height.
+      #
+      # @param args [Hash]
+      # @option args [Integer] :height block height
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { header: String }
+      def get_header_for_height(args, originator: nil)
+        raise UnsupportedActionError, 'get_header_for_height'
+      end
+
+      # Returns the network (mainnet or testnet).
+      #
+      # @param args [Hash] empty hash
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { network: String }
+      def get_network(args = {}, originator: nil)
+        raise UnsupportedActionError, 'get_network'
+      end
+
+      # Returns the wallet version string.
+      #
+      # @param args [Hash] empty hash
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { version: String }
+      def get_version(args = {}, originator: nil)
+        raise UnsupportedActionError, 'get_version'
+      end
+
+      # --- Authentication ---
+
+      # Checks if the user is authenticated.
+      #
+      # @param args [Hash] empty hash
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { authenticated: Boolean }
+      def is_authenticated(args = {}, originator: nil)
+        raise UnsupportedActionError, 'is_authenticated'
+      end
+
+      # Waits until the user is authenticated.
+      #
+      # @param args [Hash] empty hash
+      # @param originator [String, nil] FQDN of the originating application
+      # @return [Hash] { authenticated: true }
+      def wait_for_authentication(args = {}, originator: nil)
+        raise UnsupportedActionError, 'wait_for_authentication'
+      end
+
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/bsv/wallet_interface/key_deriver.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # BRC-42/43 key derivation for the wallet interface.
+    #
+    # 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
+      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)
+                    else
+                      root_key
+                    end
+      end
+
+      # Returns the identity public key as a hex string.
+      # @return [String] 66-character compressed public key hex
+      def 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)
+        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)
+        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]}-#{key_id}"
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/memory_store.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # In-memory storage adapter for testing.
+    #
+    # Stores actions, outputs, and certificates in plain Ruby arrays.
+    # Not thread-safe; intended for test use only.
+    class MemoryStore
+      include StorageAdapter
+
+      def initialize
+        @actions = []
+        @outputs = []
+        @certificates = []
+      end
+
+      def store_action(action_data)
+        @actions << action_data
+        action_data
+      end
+
+      def find_actions(query)
+        apply_pagination(filter_actions(query), query)
+      end
+
+      def count_actions(query)
+        filter_actions(query).length
+      end
+
+      def store_output(output_data)
+        @outputs << output_data
+        output_data
+      end
+
+      def find_outputs(query)
+        apply_pagination(filter_outputs(query), query)
+      end
+
+      def count_outputs(query)
+        filter_outputs(query).length
+      end
+
+      def delete_output(outpoint)
+        idx = @outputs.index { |o| o[:outpoint] == outpoint }
+        return false unless idx
+
+        @outputs.delete_at(idx)
+        true
+      end
+
+      def store_certificate(cert_data)
+        @certificates << cert_data
+        cert_data
+      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)
+      end
+
+      def delete_certificate(type:, serial_number:, certifier:)
+        idx = @certificates.index do |c|
+          c[:type] == type && c[:serial_number] == serial_number && c[:certifier] == certifier
+        end
+        return false unless idx
+
+        @certificates.delete_at(idx)
+        true
+      end
+
+      private
+
+      def filter_actions(query)
+        results = @actions
+        return results unless query[:labels]
+
+        mode = query[:label_query_mode] || 'any'
+        results.select do |a|
+          action_labels = a[:labels] || []
+          if mode == 'all'
+            (query[:labels] - action_labels).empty?
+          else
+            (query[:labels] & action_labels).any?
+          end
+        end
+      end
+
+      def filter_outputs(query)
+        results = @outputs
+        results = results.select { |o| o[:basket] == query[:basket] } if query[:basket]
+        if query[:tags]
+          mode = query[:tag_query_mode] || 'any'
+          results = results.select do |o|
+            output_tags = o[:tags] || []
+            if mode == 'all'
+              (query[:tags] - output_tags).empty?
+            else
+              (query[:tags] & output_tags).any?
+            end
+          end
+        end
+        query[:include_spent] ? results : results.reject { |o| o[:spendable] == false }
+      end
+
+      def apply_pagination(results, query)
+        offset = query[:offset] || 0
+        limit = query[:limit] || 10
+        results[offset, limit] || []
+      end
+    end
+  end
+end