bsv-wallet 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0eee112e765a4b52ce2e04895d79c1b25c0d3f26a57d56eb0cac72005dce34f0
-  data.tar.gz: 003f406ef0001d9495013d17adf802dc8c5c98ddcd85ebed0dd2c4a5aa6c1c27
+  metadata.gz: 43a1c78810a0351eb11cf29575e9d2a9e8ffca2d5e844f8122bc28dc5dfffb02
+  data.tar.gz: 358f2f7514b5d44f1896ec3ca6898cfb2e195142639711e787f545d27eda6f03
 SHA512:
-  metadata.gz: f9ca8b1c01639c0a898d8772caa893d06a17e10d41e2a80d51aec66c3c1e33b5d384e2f2ad0e717455d08444ae40dce4b661ea0c87e5ff287747be7ca9048e8f
-  data.tar.gz: 7a4abf0597b7c3b16a166e6a1d4bf7557a9de120a635a396b1b1fe10c5816ae723d53a6d66b7ac8c11cd6388a2d60346a23d7afd4845c746aba6284ca9bdfda1
+  metadata.gz: c82bcf291d49346fd574d8bf442b690575f4b42d3c66e94a8262a32ceab596831d7c9b8c69a3617e5540f29e93417014f16979aa0e345eff0b48577de6ddf10e
+  data.tar.gz: 8a5adfbe6bb90ea76d8478d181f3a453d5a9c4a15ad3a1f7eb833ef9d1b2862b5305d2dcaab016f4b10d83f5f091338f1e66c9ba3fdf0858f25597304d345308

data/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to the `bsv-wallet` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.11.0 — 2026-04-22
+
+### Added
+- `chain_data_source:` constructor param on `Client` — injectable chain
+  data provider for local blockchain queries without a remote substrate
+- `sync_utxos` restored — discovers on-chain UTXOs via the chain data
+  source and imports them into storage as `:spendable` with
+  `derivation_type: :identity`. Deduplicates transaction fetches and
+  validates UTXO API values against transaction outputs (#599)
+- `get_height` restored with local chain data fallback — returns
+  `{ height: Integer }` without requiring a substrate (#597)
+- `get_header_for_height` restored with local chain data fallback —
+  returns WoC block header JSON (#598)
+- BEEF SPV merkle root verification restored in `internalize_action`
+  when a chain data source with `valid_root_for_height?` is available;
+  error messages now distinguish SPV rejection from structural
+  invalidity (#600)
+- Store conformance shared examples extracted to
+  `lib/bsv/wallet/testing/` — downstream adapter gems can now
+  `require 'bsv/wallet/testing/store_conformance'` for interface and
+  wallet-level test coverage (#591)
+
+### Changed
+- `MemoryStore` guarded in `Client.new` — raises `ArgumentError` unless
+  `allow_memory_store: true` is passed, preventing accidental data loss
+  in production
+- Wallet-level dual-store specs refactored to use shared examples via
+  `it_behaves_like`; no test coverage lost (1281 examples preserved)
+
+### Fixed
+- `sync_utxos` deduplicates UTXO response entries before processing
+  and caches fetched transactions by txid to minimise WoC API calls
+- `internalize_action` chain tracker guard uses explicit nil check for
+  clarity
+- Consistent error message wording across `get_height` and
+  `get_header_for_height`
+
+## 0.10.0 — 2026-04-21
+
+### Added
+- BRC-100 abstract contract modules and `Client` with composition architecture
+- UTXO pool system: `UTXOPool` interface, `LocalPool` implementation, `ReplenishmentWorker`, and `utxo_pool` factory on Client
+- BRC-122 two-zone basket validation
+- `update_output_basket` on Store interface
+
+### Changed
+- `ProtoWallet` and `WalletClient` deleted, replaced with `Client` using concern modules (`Transaction`, `Crypto`, `Identity`, `Network`, `Authentication`)
+- File paths renamed from `wallet_interface` to `wallet`
+- `Store` and `BroadcastQueue` collaborators namespaced under `Client`
+- Contracts moved under `Interface` namespace
+- Legacy `ChainProvider` classes removed
+
+### Fixed
+- `internalize_payment` and `internalize_basket` now set `state: :spendable` explicitly on stored outputs
+- Derivation metadata now persisted in `store_tracked_outputs`
+- Cold start normalisation and eager validation fixes
+- SimpleCov coverage gate now requires `COVERAGE=true` explicitly
+
 ## 0.9.1 — 2026-04-16
 
 ### Changed

data/lib/bsv/wallet/broadcast_queue/inline.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module BroadcastQueue
+      # Synchronous broadcast queue adapter — the default for +Client+.
+      #
+      # +BroadcastQueue::Inline+ replicates the current wallet broadcast behaviour exactly:
+      #
+      # * With a broadcaster: calls +broadcaster.broadcast+, promotes UTXO state on
+      #   success, rolls back on failure.
+      # * Without a broadcaster: promotes immediately and returns BEEF for the
+      #   caller to broadcast manually (backwards-compatible fallback).
+      #
+      # Because this adapter executes synchronously, +async?+ returns +false+ and
+      # the caller can rely on the returned hash containing the final result.
+      class Inline
+        include BSV::Wallet::Interface::BroadcastQueue
+
+        # @param broadcaster [#broadcast, nil] broadcaster object; +nil+ disables broadcasting
+        # @param storage [BSV::Wallet::Store] wallet storage adapter
+        def initialize(storage:, broadcaster: nil)
+          @broadcaster = broadcaster
+          @storage = storage
+        end
+
+        # Returns +false+ — this adapter executes synchronously.
+        #
+        # @return [Boolean]
+        def async?
+          false
+        end
+
+        # Returns +true+ when a broadcaster has been configured.
+        #
+        # +Client+ delegates its own +broadcast_enabled?+ to this method
+        # so the check works correctly when the broadcaster is embedded in the
+        # queue rather than passed directly to the wallet.
+        #
+        # @return [Boolean]
+        def broadcast_enabled?
+          !@broadcaster.nil?
+        end
+
+        # Returns the broadcast status for a previously enqueued transaction.
+        #
+        # Delegates to storage and returns the action status field, or +nil+ if
+        # the action is not found.
+        #
+        # @param txid [String] hex transaction identifier
+        # @return [String, nil]
+        def status(txid)
+          actions = @storage.find_actions({ txid: txid, limit: 1, offset: 0 })
+          actions.first&.dig(:status)
+        end
+
+        # Broadcasts and promotes (or just promotes) a transaction synchronously.
+        #
+        # Dispatches to +broadcast_and_promote+ when a broadcaster is configured,
+        # or +promote_without_broadcast+ when none is present.
+        #
+        # @param payload [Hash] broadcast payload (see +BroadcastQueue+ module docs)
+        # @return [Hash] result hash containing at minimum +:txid+ and +:tx+
+        def enqueue(payload)
+          if @broadcaster
+            broadcast_and_promote(payload)
+          else
+            promote_without_broadcast(payload)
+          end
+        end
+
+        private
+
+        # Broadcasts the transaction and promotes storage state on success.
+        #
+        # On broadcast failure with outpoints present, rolls back all pending
+        # state (releases locked inputs, deletes change outputs, marks action
+        # failed). On failure without outpoints (finalize path), only updates
+        # the action status.
+        #
+        # INVARIANT: Only broadcast failure triggers rollback. If broadcast
+        # succeeds but promotion raises, the error propagates — confirmed
+        # on-chain outputs must never be deleted.
+        #
+        # @param payload [Hash] broadcast payload
+        # @return [Hash] result hash
+        def broadcast_and_promote(payload)
+          tx               = payload[:tx]
+          txid             = payload[:txid]
+          beef_binary      = payload[:beef_binary]
+          input_outpoints  = payload[:input_outpoints]
+          change_outpoints = payload[:change_outpoints]
+          fund_ref         = payload[:fund_ref]
+
+          begin
+            broadcast_result = @broadcaster.broadcast(tx)
+          rescue StandardError => e
+            if input_outpoints
+              rollback(input_outpoints, change_outpoints, txid, fund_ref)
+            elsif txid
+              @storage.update_action_status(txid, 'failed')
+            end
+            return {
+              txid: txid,
+              tx: beef_binary.unpack('C*'),
+              broadcast_error: e.message,
+              broadcast_status: BroadcastQueue.status_for_error(e)
+            }
+          end
+
+          # Broadcast succeeded — promote all pending state; set status to
+          # 'unproven' (transaction is on-chain but lacks a merkle proof).
+          # 'completed' is reserved for transactions confirmed by a proof-watcher.
+          promote(input_outpoints, change_outpoints, txid, status: 'unproven')
+
+          result = {
+            txid: txid,
+            tx: beef_binary.unpack('C*'),
+            broadcast_result: broadcast_result,
+            broadcast_status: 'success'
+          }
+          result[:competing_txs] = broadcast_result.competing_txs if broadcast_result.respond_to?(:competing_txs) && broadcast_result.competing_txs
+          result
+        end
+
+        # Promotes UTXO state without broadcasting.
+        #
+        # This path is reached when no broadcaster is configured. It is only
+        # valid when +accept_delayed_broadcast+ is set on the create_action
+        # call — the caller explicitly accepts that the transaction will be
+        # broadcast out-of-band. Action status is set to +unproven+.
+        #
+        # +completed+ is reserved for transactions that have received a merkle
+        # proof (set by +internalize_action+ or a future proof-watcher).
+        #
+        # Defensive guard: raises +WalletError+ if reached without
+        # +accept_delayed_broadcast+. The normal entry point for this guard is
+        # the +create_action+ validation added in Task 1 (#456), but this guard
+        # protects against other code paths that bypass it.
+        #
+        # @param payload [Hash] broadcast payload
+        # @return [Hash] result hash containing +:txid+ and +:tx+
+        # @raise [BSV::Wallet::WalletError] if +accept_delayed_broadcast+ is not set
+        def promote_without_broadcast(payload)
+          txid             = payload[:txid]
+          beef_binary      = payload[:beef_binary]
+          input_outpoints  = payload[:input_outpoints]
+          change_outpoints = payload[:change_outpoints]
+          delayed          = payload[:accept_delayed_broadcast]
+
+          unless delayed
+            raise BSV::Wallet::WalletError,
+                  'BroadcastQueue::Inline cannot promote without a broadcaster unless ' \
+                  'accept_delayed_broadcast is set. This indicates a bypass of ' \
+                  'the create_action guard — report as a bug.'
+          end
+
+          promote(input_outpoints, change_outpoints, txid, status: 'unproven')
+
+          { txid: txid, tx: beef_binary.unpack('C*') }
+        end
+
+        # Promotes UTXO state: marks inputs as +:spent+, change as +:spendable+,
+        # and updates the action status.
+        #
+        # When +outpoints+ arguments are +nil+ (finalize path), UTXO transitions
+        # are skipped and only the action status is updated.
+        #
+        # @param input_outpoints [Array<String>, nil]
+        # @param change_outpoints [Array<String>, nil]
+        # @param txid [String, nil]
+        # @param status [String]
+        def promote(input_outpoints, change_outpoints, txid, status: 'completed')
+          Array(input_outpoints).each { |op| @storage.update_output_state(op, :spent) }
+          Array(change_outpoints).each { |op| @storage.update_output_state(op, :spendable) }
+          @storage.update_action_status(txid, status) if txid
+        end
+
+        # Rolls back a pending auto-funded action.
+        #
+        # Releases locked inputs (only those matching +fund_ref+), deletes phantom
+        # change outputs, and marks the action as +failed+.
+        #
+        # @param input_outpoints [Array<String>] outpoints locked as inputs
+        # @param change_outpoints [Array<String>] change outputs to delete
+        # @param txid [String, nil] action txid
+        # @param fund_ref [String] fund reference used when locking inputs
+        def rollback(input_outpoints, change_outpoints, txid, fund_ref)
+          Array(input_outpoints).each do |op|
+            outputs = @storage.find_outputs({ outpoint: op, include_spent: true, limit: 1, offset: 0 })
+            next if outputs.empty?
+            next unless outputs.first[:pending_reference] == fund_ref
+
+            @storage.update_output_state(op, :spendable)
+          end
+          Array(change_outpoints).each { |op| @storage.delete_output(op) }
+          @storage.update_action_status(txid, 'failed') if txid
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/broadcast_queue.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Broadcast queue implementations. See {Interface::BroadcastQueue} for the contract.
+    module BroadcastQueue
+      autoload :Inline, 'bsv/wallet/broadcast_queue/inline'
+
+      # Maps a broadcast exception to a status string.
+      #
+      # Shared helper so all queue adapters produce consistent status strings.
+      #
+      # @param error [StandardError] the exception raised during broadcast
+      # @return [String] one of +'doubleSpend'+, +'invalidTx'+, +'serviceError'+
+      def self.status_for_error(error)
+        return 'serviceError' unless error.is_a?(BSV::Network::BroadcastError)
+
+        arc_status = error.arc_status.to_s.upcase
+        return 'doubleSpend' if arc_status == 'DOUBLE_SPEND_ATTEMPTED'
+
+        invalid_statuses = %w[REJECTED INVALID MALFORMED MINED_IN_STALE_BLOCK]
+        return 'invalidTx' if invalid_statuses.include?(arc_status) || arc_status.include?('ORPHAN')
+
+        'serviceError'
+      end
+    end
+  end
+end

data/lib/bsv/wallet/client/brc100/authentication.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    class Client
+      # Authentication methods for {Client}.
+      module Authentication
+        # Checks whether the user is authenticated.
+        #
+        # @return [Hash] { authenticated: Boolean }
+        def is_authenticated(args = {}, originator: nil)
+          return @substrate.is_authenticated(args, originator: originator) if @substrate
+
+          { authenticated: true }
+        end
+
+        # Waits until the user is authenticated.
+        #
+        # @return [Hash] { authenticated: true }
+        def wait_for_authentication(args = {}, originator: nil)
+          return @substrate.wait_for_authentication(args, originator: originator) if @substrate
+
+          { authenticated: true }
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/client/brc100/crypto.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module BSV
+  module Wallet
+    class Client
+      # Cryptographic operations for the BRC-100 wallet client.
+      #
+      # Provides the 9 crypto public methods defined by the BRC-100 interface:
+      # key derivation, symmetric encryption/decryption, HMAC creation/verification,
+      # ECDSA signing/verification, and key linkage revelation.
+      #
+      # All methods delegate to @substrate when present. Otherwise they operate
+      # against @key_deriver directly.
+      module Crypto
+        # Returns a derived or identity public key.
+        #
+        # @param args [Hash]
+        # @option args [Boolean] :identity_key return the identity key instead of deriving
+        # @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
+        # @return [Hash] { public_key: String } hex-encoded compressed public key
+        def get_public_key(args, originator: nil)
+          return @substrate.get_public_key(args, originator: originator) if @substrate
+
+          if args[:identity_key]
+            { public_key: @key_deriver.identity_key }
+          else
+            counterparty = args[:counterparty] || 'self'
+            pub = @key_deriver.derive_public_key(
+              args[:protocol_id],
+              args[:key_id],
+              counterparty,
+              for_self: args[:for_self] || false
+            )
+            { public_key: pub.to_hex }
+          end
+        end
+
+        # Encrypts plaintext using AES-256-GCM with 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'
+        # @return [Hash] { ciphertext: Array<Integer> }
+        def encrypt(args, originator: nil)
+          return @substrate.encrypt(args, originator: originator) if @substrate
+
+          sym_key = derive_sym_key(args)
+          ciphertext = sym_key.encrypt(bytes_to_string(args[:plaintext]))
+          { ciphertext: string_to_bytes(ciphertext) }
+        end
+
+        # Decrypts ciphertext using AES-256-GCM with 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'
+        # @return [Hash] { plaintext: Array<Integer> }
+        def decrypt(args, originator: nil)
+          return @substrate.decrypt(args, originator: originator) if @substrate
+
+          sym_key = derive_sym_key(args)
+          plaintext = sym_key.decrypt(bytes_to_string(args[:ciphertext]))
+          { plaintext: string_to_bytes(plaintext) }
+        end
+
+        # Creates an HMAC-SHA256 using a derived symmetric key.
+        #
+        # @param args [Hash]
+        # @option args [Array<Integer>] :data byte array to authenticate
+        # @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'
+        # @return [Hash] { hmac: Array<Integer> }
+        def create_hmac(args, originator: nil)
+          return @substrate.create_hmac(args, originator: originator) if @substrate
+
+          sym_key = derive_sym_key(args)
+          hmac = BSV::Primitives::Digest.hmac_sha256(sym_key.to_bytes, bytes_to_string(args[:data]))
+          { hmac: string_to_bytes(hmac) }
+        end
+
+        # Verifies an HMAC-SHA256 using a derived symmetric key.
+        #
+        # @param args [Hash]
+        # @option args [Array<Integer>] :data byte array that was authenticated
+        # @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'
+        # @return [Hash] { valid: true }
+        # @raise [InvalidHmacError] if the HMAC does not match
+        def verify_hmac(args, originator: nil)
+          return @substrate.verify_hmac(args, originator: originator) if @substrate
+
+          sym_key = derive_sym_key(args)
+          expected = BSV::Primitives::Digest.hmac_sha256(sym_key.to_bytes, bytes_to_string(args[:data]))
+          provided = bytes_to_string(args[:hmac])
+
+          raise InvalidHmacError unless secure_compare(expected, provided)
+
+          { valid: true }
+        end
+
+        # Creates an ECDSA signature using a derived private key.
+        #
+        # @param args [Hash]
+        # @option args [Array<Integer>] :data data to hash and sign
+        # @option args [Array<Integer>] :hash_to_directly_sign pre-computed 32-byte hash 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'
+        # @return [Hash] { signature: Array<Integer> } DER-encoded signature as byte array
+        def create_signature(args, originator: nil)
+          return @substrate.create_signature(args, originator: originator) if @substrate
+
+          counterparty = args[:counterparty] || 'anyone'
+          priv_key = @key_deriver.derive_private_key(args[:protocol_id], args[:key_id], counterparty)
+
+          hash = if args[:hash_to_directly_sign]
+                   bytes_to_string(args[:hash_to_directly_sign])
+                 else
+                   BSV::Primitives::Digest.sha256(bytes_to_string(args[:data]))
+                 end
+
+          sig = priv_key.sign(hash)
+          { signature: string_to_bytes(sig.to_der) }
+        end
+
+        # Verifies an ECDSA signature using a derived public key.
+        #
+        # @param args [Hash]
+        # @option args [Array<Integer>] :data original data that was signed
+        # @option args [Array<Integer>] :hash_to_directly_verify pre-computed 32-byte hash
+        # @option args [Array<Integer>] :signature DER-encoded signature as 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] :for_self verify own derived key (default false)
+        # @return [Hash] { valid: true }
+        # @raise [InvalidSignatureError] if the signature does not verify
+        def verify_signature(args, originator: nil)
+          return @substrate.verify_signature(args, originator: originator) if @substrate
+
+          counterparty = args[:counterparty] || 'self'
+          for_self = args[:for_self] || false
+
+          pub_key = @key_deriver.derive_public_key(
+            args[:protocol_id],
+            args[:key_id],
+            counterparty,
+            for_self: for_self
+          )
+
+          hash = if args[:hash_to_directly_verify]
+                   bytes_to_string(args[:hash_to_directly_verify])
+                 else
+                   BSV::Primitives::Digest.sha256(bytes_to_string(args[:data]))
+                 end
+
+          sig = BSV::Primitives::Signature.from_der(bytes_to_string(args[:signature]))
+          valid = pub_key.verify(hash, sig)
+
+          raise InvalidSignatureError unless valid
+
+          { valid: true }
+        end
+
+        # Reveals counterparty key linkage to a verifier (BRC-69 Method 1).
+        #
+        # @param args [Hash]
+        # @option args [String] :counterparty counterparty public key hex (not 'self')
+        # @option args [String] :verifier verifier public key hex
+        # @return [Hash] with :prover, :verifier, :counterparty, :revelation_time,
+        #   :encrypted_linkage, :encrypted_linkage_proof
+        def reveal_counterparty_key_linkage(args, originator: nil)
+          return @substrate.reveal_counterparty_key_linkage(args, originator: originator) if @substrate
+
+          counterparty = args[:counterparty]
+          verifier = args[:verifier]
+
+          raise InvalidParameterError.new('counterparty', 'a specific public key hex, not "anyone"') if counterparty == 'anyone'
+
+          Validators.validate_pub_key_hex!(verifier, 'verifier')
+
+          linkage = @key_deriver.reveal_counterparty_secret(counterparty)
+          revelation_time = Time.now.utc.iso8601
+
+          encrypted_linkage_result = encrypt({
+                                               plaintext: string_to_bytes(linkage),
+                                               protocol_id: [2, 'counterparty linkage revelation'],
+                                               key_id: revelation_time,
+                                               counterparty: verifier
+                                             })
+
+          counterparty_pub = BSV::Primitives::PublicKey.from_hex(counterparty)
+          linkage_point = BSV::Primitives::PublicKey.from_bytes(linkage)
+          schnorr_proof = BSV::Primitives::Schnorr.generate_proof(
+            @key_deriver.root_key,
+            @key_deriver.root_key.public_key,
+            counterparty_pub,
+            linkage_point
+          )
+
+          z_bytes = schnorr_proof.z.to_s(2)
+          z_bytes = ("\x00".b * (32 - z_bytes.length)) + z_bytes if z_bytes.length < 32
+          proof_bin = schnorr_proof.r.compressed + schnorr_proof.s_prime.compressed + z_bytes
+
+          encrypted_proof_result = encrypt({
+                                             plaintext: string_to_bytes(proof_bin),
+                                             protocol_id: [2, 'counterparty linkage revelation'],
+                                             key_id: revelation_time,
+                                             counterparty: verifier
+                                           })
+
+          {
+            prover: @key_deriver.identity_key,
+            verifier: verifier,
+            counterparty: counterparty,
+            revelation_time: revelation_time,
+            encrypted_linkage: encrypted_linkage_result[:ciphertext],
+            encrypted_linkage_proof: encrypted_proof_result[:ciphertext]
+          }
+        end
+
+        # Reveals specific key linkage for a particular interaction (BRC-69 Method 2).
+        #
+        # @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
+        # @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)
+          return @substrate.reveal_specific_key_linkage(args, originator: originator) if @substrate
+
+          counterparty = args[:counterparty]
+          verifier = args[:verifier]
+          protocol_id = args[:protocol_id]
+          key_id = args[:key_id]
+
+          raise InvalidParameterError.new('counterparty', 'a specific public key hex, not "anyone"') if counterparty == 'anyone'
+
+          Validators.validate_pub_key_hex!(verifier, 'verifier')
+
+          linkage = @key_deriver.reveal_specific_secret(counterparty, protocol_id, key_id)
+
+          derived_protocol = "specific linkage revelation #{protocol_id[0]} #{protocol_id[1]}"
+
+          encrypted_linkage_result = encrypt({
+                                               plaintext: string_to_bytes(linkage),
+                                               protocol_id: [2, derived_protocol],
+                                               key_id: key_id,
+                                               counterparty: verifier
+                                             })
+
+          encrypted_proof_result = encrypt({
+                                             plaintext: [0],
+                                             protocol_id: [2, derived_protocol],
+                                             key_id: key_id,
+                                             counterparty: verifier
+                                           })
+
+          {
+            prover: @key_deriver.identity_key,
+            verifier: verifier,
+            counterparty: counterparty,
+            protocol_id: protocol_id,
+            key_id: key_id,
+            encrypted_linkage: encrypted_linkage_result[:ciphertext],
+            encrypted_linkage_proof: encrypted_proof_result[:ciphertext],
+            proof_type: 0
+          }
+        end
+
+        private
+
+        def derive_sym_key(args)
+          counterparty = args[:counterparty] || 'self'
+          @key_deriver.derive_symmetric_key(args[:protocol_id], args[:key_id], counterparty)
+        end
+
+        def bytes_to_string(bytes)
+          bytes.pack('C*')
+        end
+
+        def string_to_bytes(str)
+          str.unpack('C*')
+        end
+
+        def secure_compare(a, b)
+          return false unless a.bytesize == b.bytesize
+
+          if OpenSSL.respond_to?(:fixed_length_secure_compare)
+            OpenSSL.fixed_length_secure_compare(a, b)
+          else
+            result = 0
+            a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+            result.zero?
+          end
+        end
+      end
+    end
+  end
+end