bsv-sdk 0.23.1 → 0.25.0

data/lib/bsv/transaction/{transaction.rb → tx.rb}

@@ -10,12 +10,12 @@ module BSV
     # estimation.
     #
     # @example Build, sign, and serialise a transaction
-    #   tx = BSV::Transaction::Transaction.new
+    #   tx = BSV::Transaction::Tx.new
     #   tx.add_input(input)
     #   tx.add_output(output)
     #   tx.sign(0, private_key)
     #   tx.to_hex #=> "0100000001..."
-    class Transaction
+    class Tx
       # Estimated size of an unsigned P2PKH input in bytes.
       UNSIGNED_P2PKH_INPUT_SIZE = 148
 
@@ -59,7 +59,7 @@ module BSV
 
       # Append a transaction input.
       #
-      # @param input [TransactionInput] the input to add
+      # @param input [Transaction::TransactionInput] the input to add
       # @return [self] for chaining
       def add_input(input)
         @inputs << input
@@ -68,7 +68,7 @@ module BSV
 
       # Append a transaction output.
       #
-      # @param output [TransactionOutput] the output to add
+      # @param output [Transaction::TransactionOutput] the output to add
       # @return [self] for chaining
       def add_output(output)
         @outputs << output
@@ -144,7 +144,7 @@ module BSV
       # Deserialise a transaction from binary data.
       #
       # @param data [String] raw binary transaction
-      # @return [Transaction] the parsed transaction
+      # @return [Transaction::Tx] the parsed transaction
       def self.from_binary(data)
         raise ArgumentError, "truncated transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
 
@@ -182,7 +182,7 @@ module BSV
       # Deserialise a transaction from a hex string.
       #
       # @param hex [String] hex-encoded transaction
-      # @return [Transaction] the parsed transaction
+      # @return [Transaction::Tx] the parsed transaction
       def self.from_hex(hex)
         from_binary(BSV::Primitives::Hex.decode(hex, name: 'transaction hex'))
       end
@@ -190,7 +190,7 @@ module BSV
       # Deserialise a transaction from Extended Format (BRC-30) binary data.
       #
       # @param data [String] raw EF binary
-      # @return [Transaction] the parsed transaction with source data on inputs
+      # @return [Transaction::Tx] the parsed transaction with source data on inputs
       # @raise [ArgumentError] if the EF marker is invalid
       def self.from_ef(data)
         raise ArgumentError, "truncated EF transaction: need at least 10 bytes, got #{data.bytesize}" if data.bytesize < 10
@@ -250,7 +250,7 @@ module BSV
       # Deserialise a transaction from an Extended Format hex string.
       #
       # @param hex [String] hex-encoded EF transaction
-      # @return [Transaction] the parsed transaction with source data on inputs
+      # @return [Transaction::Tx] the parsed transaction with source data on inputs
       def self.from_ef_hex(hex)
         from_ef(BSV::Primitives::Hex.decode(hex, name: 'EF transaction hex'))
       end
@@ -260,7 +260,7 @@ module BSV
       #
       # @param data [String] binary data containing the transaction
       # @param offset [Integer] byte offset to start reading from
-      # @return [Array(Transaction, Integer)] the transaction and bytes consumed
+      # @return [Array(Transaction::Tx, Integer)] the transaction and bytes consumed
       def self.from_binary_with_offset(data, offset = 0)
         if data.bytesize < offset + 10
           raise ArgumentError, "truncated transaction: need at least 10 bytes at offset #{offset}, got #{data.bytesize - offset}"
@@ -331,7 +331,7 @@ module BSV
         bump_index_by_height = build_beef_bumps(beef, ancestors)
         BSV.logger&.debug do
           proven = ancestors.count(&:merkle_path)
-          "[Transaction] BEEF: #{ancestors.length} ancestors, #{proven} proven " \
+          "[Tx] BEEF: #{ancestors.length} ancestors, #{proven} proven " \
             "across #{bump_index_by_height.length} block heights"
         end
 
@@ -370,7 +370,7 @@ module BSV
       # +wire_source_transactions+ pass in +Beef.from_binary+.
       #
       # @param data [String] raw BEEF binary
-      # @return [Transaction, nil] the subject transaction with ancestry wired,
+      # @return [Transaction::Tx, nil] the subject transaction with ancestry wired,
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef(data)
         beef = Beef.from_binary(data)
@@ -384,7 +384,7 @@ module BSV
       # Parse a BEEF hex string and return the subject transaction.
       #
       # @param hex [String] hex-encoded BEEF
-      # @return [Transaction, nil] the subject transaction with ancestry wired,
+      # @return [Transaction::Tx, nil] the subject transaction with ancestry wired,
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef_hex(hex)
         from_beef(BSV::Primitives::Hex.decode(hex, name: 'BEEF hex'))
@@ -400,7 +400,7 @@ module BSV
       # @return [String] 32-byte transaction ID in wire byte order
       def wtxid
         id = BSV::Primitives::Digest.sha256d(to_binary)
-        BSV.logger&.debug { "[Transaction] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
+        BSV.logger&.debug { "[Tx] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
         id
       end
 
@@ -622,7 +622,7 @@ module BSV
       # - +:script_failure+ — Ruby raises; TS/Python return +false+; Go also propagates errors
       # - +:missing_source+ — Ruby raises; consistent with TS/Go/Python (all raise/error)
       #
-      # @param chain_tracker [ChainTracker] chain tracker for merkle root validation
+      # @param chain_tracker [Transaction::ChainTracker] chain tracker for merkle root validation
       # @param fee_model [FeeModel, nil] optional fee model to validate the root transaction's fee
       # @return [true] on successful verification
       # @raise [VerificationError] with code +:invalid_merkle_proof+ if a merkle proof is invalid
@@ -729,7 +729,7 @@ module BSV
       # @return [Integer] estimated fee in satoshis (rounded up)
       def estimated_fee(satoshis_per_byte: 0.1)
         unless self.class.instance_variable_get(:@_estimated_fee_warned)
-          warn '[DEPRECATION] BSV::Transaction::Transaction#estimated_fee is deprecated. ' \
+          warn '[DEPRECATION] BSV::Transaction::Tx#estimated_fee is deprecated. ' \
                'Use BSV::Transaction::FeeModels::SatoshisPerKilobyte.new.compute_fee(tx) instead.', uplevel: 1
           self.class.instance_variable_set(:@_estimated_fee_warned, true)
         end
@@ -806,7 +806,7 @@ module BSV
       # is required. Otherwise, requires a wired +source_transaction+ and a
       # valid output at +prev_tx_out_index+.
       #
-      # @param input [TransactionInput]
+      # @param input [Transaction::TransactionInput]
       # @param idx [Integer] input index, used in error messages
       # @return [TransactionOutput, nil]
       def ef_source_output(input, idx)
@@ -913,12 +913,12 @@ module BSV
 
         if tx.merkle_path
           BSV.logger&.debug do
-            "[Transaction] ancestor: #{tx.dtxid_hex} proven at height #{tx.merkle_path.block_height} (leaf stop)"
+            "[Tx] ancestor: #{tx.dtxid_hex} proven at height #{tx.merkle_path.block_height} (leaf stop)"
           end
         else
           tx.inputs.each_with_index do |input, idx|
             unless input.source_transaction
-              BSV.logger&.debug { "[Transaction] ancestor: #{tx.dtxid_hex} input #{idx} has no source_transaction (skipped)" }
+              BSV.logger&.debug { "[Tx] ancestor: #{tx.dtxid_hex} input #{idx} has no source_transaction (skipped)" }
               next
             end
 

data/lib/bsv/transaction/unlocking_script_template.rb

@@ -14,7 +14,7 @@ module BSV
     class UnlockingScriptTemplate
       # Generate the unlocking script for a transaction input.
       #
-      # @param _tx [Transaction] the transaction being signed
+      # @param _tx [Transaction::Tx] the transaction being signed
       # @param _input_index [Integer] the input index to sign
       # @return [Script::Script] the generated unlocking script
       # @raise [NotImplementedError] if not overridden by a subclass
@@ -24,7 +24,7 @@ module BSV
 
       # Estimate the unlocking script length in bytes (for fee estimation).
       #
-      # @param _tx [Transaction] the transaction
+      # @param _tx [Transaction::Tx] the transaction
       # @param _input_index [Integer] the input index
       # @return [Integer] estimated script length in bytes
       # @raise [NotImplementedError] if not overridden by a subclass

data/lib/bsv/transaction.rb

@@ -3,7 +3,7 @@
 module BSV
   # Transaction building, signing, serialisation, and verification.
   #
-  # Provides the {Transaction::Transaction} class for constructing and signing
+  # Provides the {Transaction::Tx} class for constructing and signing
   # transactions, {Transaction::Beef} for BEEF (BRC-62/95/96) serialisation,
   # {Transaction::MerklePath} for BRC-74 merkle proofs, and
   # {Transaction::Sighash} constants for BIP-143 sighash computation.
@@ -19,8 +19,9 @@ module BSV
     autoload :ChainTracker,             'bsv/transaction/chain_tracker'
     autoload :ChainTrackers,            'bsv/transaction/chain_trackers'
     autoload :Beef,                     'bsv/transaction/beef'
+    autoload :BeefParty, 'bsv/transaction/beef_party'
     autoload :UnlockingScriptTemplate,  'bsv/transaction/unlocking_script_template'
     autoload :P2PKH,                    'bsv/transaction/p2pkh'
-    autoload :Transaction,              'bsv/transaction/transaction'
+    autoload :Tx,                       'bsv/transaction/tx'
   end
 end

data/lib/bsv/version.rb

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

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

@@ -34,6 +34,19 @@ module BSV
           @identity_key ||= @root_key.public_key.to_hex
         end
 
+        # Returns the identity public key as a 33-byte compressed binary string.
+        #
+        # Pubkeys are hex-canonical in this SDK (see ADR-001 — the documented
+        # exception to binary-internal), so {#identity_key} (hex) is the
+        # default. This binary accessor exists for the rare sites that need
+        # raw bytes (e.g. feeding +BSV::Primitives::Hash#hash160+) without
+        # round-tripping hex → binary at each call.
+        #
+        # @return [String] 33-byte compressed public key binary
+        def identity_key_bytes
+          @identity_key_bytes ||= @root_key.public_key.compressed
+        end
+
         # Derives a public key using BRC-42 key derivation.
         #
         # @param protocol_id [Array] [security_level, protocol_name]

data/lib/bsv/wallet/proto_wallet.rb

@@ -167,7 +167,7 @@ module BSV
         priv_key = @key_deriver.derive_private_key(protocol_id, key_id, counterparty)
 
         hash = if hash_to_directly_sign
-                 bytes_to_string(hash_to_directly_sign)
+                 validate_hash_32!(hash_to_directly_sign, 'hash_to_directly_sign')
                else
                  BSV::Primitives::Digest.sha256(bytes_to_string(data))
                end
@@ -203,7 +203,7 @@ module BSV
         )
 
         hash = if hash_to_directly_verify
-                 bytes_to_string(hash_to_directly_verify)
+                 validate_hash_32!(hash_to_directly_verify, 'hash_to_directly_verify')
                else
                  BSV::Primitives::Digest.sha256(bytes_to_string(data))
                end
@@ -347,6 +347,16 @@ module BSV
         bytes.is_a?(String) ? bytes.b : bytes.pack('C*')
       end
 
+      # Coerce a hash parameter to a 32-byte binary string, raising
+      # InvalidParameterError if the input has the wrong length. Accepts
+      # either a binary String or an Array<Integer> per BRC-100 convention.
+      def validate_hash_32!(value, name)
+        bytes = bytes_to_string(value)
+        raise InvalidParameterError.new(name, "exactly 32 bytes, got #{bytes.bytesize}") unless bytes.bytesize == 32
+
+        bytes
+      end
+
       # Normalise a public key argument to a 66-character compressed hex string.
       # Accepts either a 33-byte binary string or a 66-character hex string.
       def normalise_pubkey_hex(value)

data/lib/bsv/wallet/serializer/create_signature.rb

@@ -30,6 +30,13 @@ module BSV
             end
             raise BSV::Wallet::InvalidParameterError.new('data or hash_to_directly_sign', 'present') unless data || hash
 
+            if hash && hash.bytesize != HASH_SIZE
+              raise BSV::Wallet::InvalidParameterError.new(
+                'hash_to_directly_sign',
+                "exactly #{HASH_SIZE} bytes, got #{hash.bytesize}"
+              )
+            end
+
             w = BSV::Wallet::Wire::Writer.new
             Common.write_key_related_params(
               w,

data/lib/bsv/wallet/serializer/get_public_key.rb

@@ -66,6 +66,10 @@ module BSV
 
         # Result wire layout:
         #   [33 bytes: compressed public key]
+        #
+        # The wire bytes are 33-byte compressed binary by the BRC-103 protocol,
+        # but the Ruby return shape is hex per the BRC-100 PubKeyHex contract
+        # (ADR-001 — pubkeys are the documented hex exception to binary-internal).
         module Result
           module_function
 
@@ -77,7 +81,7 @@ module BSV
           def deserialize(bytes)
             raise ArgumentError, "public key too short: #{bytes.bytesize}" if bytes.bytesize < PUBKEY_SIZE
 
-            { public_key: bytes.byteslice(0, PUBKEY_SIZE) }
+            { public_key: bytes.byteslice(0, PUBKEY_SIZE).unpack1('H*') }
           end
         end
       end

data/lib/bsv/wallet/serializer/reveal_counterparty_key_linkage.rb

@@ -75,11 +75,14 @@ module BSV
             w.buf
           end
 
+          # Pubkey fields are returned as 66-char hex per the BRC-100 PubKeyHex
+          # contract (ADR-001 — pubkeys are the documented hex exception to
+          # binary-internal). Wire bytes stay 33-byte compressed binary.
           def deserialize(bytes)
             r = BSV::Wallet::Wire::Reader.new(bytes)
-            prover       = r.read_bytes(PUBKEY_SIZE)
-            verifier     = r.read_bytes(PUBKEY_SIZE)
-            counterparty = r.read_bytes(PUBKEY_SIZE)
+            prover       = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            verifier     = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            counterparty = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
             revelation_time = r.read_str_with_varint_len
             el_len = r.read_varint
             encrypted_linkage = r.read_bytes(el_len)

data/lib/bsv/wallet/serializer/reveal_specific_key_linkage.rb

@@ -78,11 +78,14 @@ module BSV
             w.buf
           end
 
+          # Pubkey fields are returned as 66-char hex per the BRC-100 PubKeyHex
+          # contract (ADR-001 — pubkeys are the documented hex exception to
+          # binary-internal). Wire bytes stay 33-byte compressed binary.
           def deserialize(bytes)
             r = BSV::Wallet::Wire::Reader.new(bytes)
-            prover       = r.read_bytes(PUBKEY_SIZE)
-            verifier     = r.read_bytes(PUBKEY_SIZE)
-            counterparty = r.read_bytes(PUBKEY_SIZE)
+            prover       = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            verifier     = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
+            counterparty = r.read_bytes(PUBKEY_SIZE).unpack1('H*')
             protocol_id  = Common.read_protocol(r)
             key_id_len   = r.read_varint
             key_id       = r.read_bytes(key_id_len).force_encoding('UTF-8')

data/lib/bsv/wallet/serializer/verify_signature.rb

@@ -34,6 +34,13 @@ module BSV
             raise BSV::Wallet::InvalidParameterError.new('data or hash_to_directly_verify', 'present') unless data || hash
             raise BSV::Wallet::InvalidParameterError.new('signature', 'present') unless sig
 
+            if hash && hash.bytesize != HASH_SIZE
+              raise BSV::Wallet::InvalidParameterError.new(
+                'hash_to_directly_verify',
+                "exactly #{HASH_SIZE} bytes, got #{hash.bytesize}"
+              )
+            end
+
             w = BSV::Wallet::Wire::Writer.new
             Common.write_key_related_params(
               w,

data/lib/bsv-sdk.rb

@@ -26,6 +26,8 @@ module BSV
   autoload :Identity,    'bsv/identity'
   autoload :Registry,    'bsv/registry'
   autoload :MCP,         'bsv/mcp'
+  autoload :Storage,     'bsv/storage'
+  autoload :KVStore,     'bsv/kv_store'
 
   # Wallet is loaded eagerly to avoid load-path shadowing when bsv-wallet is
   # also in the bundle (bsv-wallet/lib/bsv/wallet.rb would otherwise win).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.25.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -85,6 +85,11 @@ files:
 - lib/bsv/identity/constants.rb
 - lib/bsv/identity/identity_parser.rb
 - lib/bsv/identity/types.rb
+- lib/bsv/kv_store.rb
+- lib/bsv/kv_store/entry.rb
+- lib/bsv/kv_store/global.rb
+- lib/bsv/kv_store/interpreter.rb
+- lib/bsv/kv_store/token.rb
 - lib/bsv/mcp.rb
 - lib/bsv/mcp/config.rb
 - lib/bsv/mcp/server.rb
@@ -118,6 +123,7 @@ files:
 - lib/bsv/overlay/broadcast_facilitator.rb
 - lib/bsv/overlay/constants.rb
 - lib/bsv/overlay/errors.rb
+- lib/bsv/overlay/historian.rb
 - lib/bsv/overlay/host_reputation_tracker.rb
 - lib/bsv/overlay/lookup_facilitator.rb
 - lib/bsv/overlay/lookup_resolver.rb
@@ -152,6 +158,7 @@ files:
 - lib/bsv/registry/constants.rb
 - lib/bsv/registry/types.rb
 - lib/bsv/script.rb
+- lib/bsv/script/bip276.rb
 - lib/bsv/script/builder.rb
 - lib/bsv/script/chunk.rb
 - lib/bsv/script/interpreter/error.rb
@@ -169,8 +176,13 @@ files:
 - lib/bsv/script/push_drop_template.rb
 - lib/bsv/script/script.rb
 - lib/bsv/secp256k1_native.bundle
+- lib/bsv/storage.rb
+- lib/bsv/storage/downloader.rb
+- lib/bsv/storage/errors.rb
+- lib/bsv/storage/utils.rb
 - lib/bsv/transaction.rb
 - lib/bsv/transaction/beef.rb
+- lib/bsv/transaction/beef_party.rb
 - lib/bsv/transaction/chain_tracker.rb
 - lib/bsv/transaction/chain_trackers.rb
 - lib/bsv/transaction/chain_trackers/whats_on_chain.rb
@@ -181,9 +193,9 @@ files:
 - lib/bsv/transaction/merkle_path.rb
 - lib/bsv/transaction/p2pkh.rb
 - lib/bsv/transaction/sighash.rb
-- lib/bsv/transaction/transaction.rb
 - lib/bsv/transaction/transaction_input.rb
 - lib/bsv/transaction/transaction_output.rb
+- lib/bsv/transaction/tx.rb
 - lib/bsv/transaction/unlocking_script_template.rb
 - lib/bsv/transaction/var_int.rb
 - lib/bsv/transaction/verification_error.rb