bsv-sdk 0.20.0 → 0.23.0

data/lib/bsv/wallet/wire/validation.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Wire
+      # Branded-type validators for BRC-100 parameters.
+      #
+      # Each method raises InvalidParameterError on failure and returns nil
+      # on success. Port of ts-sdk/src/wallet/validationHelpers.ts.
+      #
+      # The existing ProtoWallet::Validators module delegates here so there
+      # is a single source of truth for all parameter validation logic.
+      module Validation
+        module_function
+
+        MAX_SATOSHIS = 21_000_000 * (10**8)
+
+        # Validates that +value+ is a hex string (even length, hex chars only).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        # @param length [Integer, nil] expected number of hex chars (nil = any)
+        def hex_string!(name, value, length: nil)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          raise InvalidParameterError.new(name, 'a hex string (characters 0-9, a-f, A-F only)') unless value.match?(/\A[0-9a-fA-F]*\z/)
+
+          raise InvalidParameterError.new(name, 'a hex string with even number of characters') if value.length.odd?
+
+          return unless length && value.length != length
+
+          raise InvalidParameterError.new(name, "a #{length}-character hex string, got #{value.length}")
+        end
+
+        # Validates that +value+ is a Base64-encoded string.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def base64_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          return if value.match?(%r{\A[A-Za-z0-9+/]*={0,2}\z})
+
+          raise InvalidParameterError.new(name, 'a valid Base64 string')
+        end
+
+        # Validates an outpoint string in the form "<64-hex-txid>.<vout>".
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def outpoint_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          parts = value.split('.', 2)
+          raise InvalidParameterError.new(name, 'an outpoint string in the format <64-hex-txid>.<vout>') unless parts.length == 2
+
+          txid_hex, vout_str = parts
+
+          raise InvalidParameterError.new(name, 'an outpoint with a 64-character hex transaction ID') unless txid_hex.match?(/\A[0-9a-fA-F]{64}\z/)
+
+          raise InvalidParameterError.new(name, 'an outpoint with a non-negative integer output index') unless vout_str.match?(/\A\d+\z/)
+
+          vout = vout_str.to_i
+          return unless vout > 0xFFFFFFFF
+
+          raise InvalidParameterError.new(name, 'an outpoint with a vout that fits in a uint32 (0..4294967295)')
+        end
+
+        # Validates a compressed public key in hex form (66 chars, 02/03 prefix).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def pub_key_hex!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          return if value.match?(/\A0[23][0-9a-fA-F]{64}\z/)
+
+          raise InvalidParameterError.new(name, 'a 66-character compressed public key hex string (02 or 03 prefix)')
+        end
+
+        # Validates a description string (5..50 printable characters).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def description_5_to_50!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          len = value.length
+          raise InvalidParameterError.new(name, 'between 5 and 50 characters') if len < 5 || len > 50
+        end
+
+        # Validates a label string (1..150 characters, no spaces).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def label_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          len = value.length
+          raise InvalidParameterError.new(name, 'between 1 and 150 characters') if len < 1 || len > 150
+        end
+
+        # Validates a basket name (1..300 characters).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def basket_string!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          len = value.length
+          raise InvalidParameterError.new(name, 'between 1 and 300 characters') if len < 1 || len > 300
+        end
+
+        # Validates an originator domain (1..250 bytes UTF-8).
+        # The originator must fit in a single-byte length field in the wire frame.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def originator_domain!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          byte_len = value.bytesize
+          raise InvalidParameterError.new(name, 'at most 250 bytes') if byte_len > 250
+        end
+
+        # Validates a satoshi amount (0..21_000_000 * 10^8).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def satoshi_value!(name, value)
+          raise InvalidParameterError.new(name, 'a non-negative integer') unless value.is_a?(Integer)
+
+          return unless value.negative? || value > MAX_SATOSHIS
+
+          raise InvalidParameterError.new(name, "between 0 and #{MAX_SATOSHIS} satoshis")
+        end
+
+        # Validates a non-negative integer.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def positive_integer_or_zero!(name, value)
+          return if value.is_a?(Integer) && !value.negative?
+
+          raise InvalidParameterError.new(name, 'a non-negative integer')
+        end
+
+        # Validates a BRC-43 protocol name string (5..400 chars, lowercase).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def protocol_string_5_to_400!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          normalized = value.strip.downcase
+          max_length = normalized.start_with?('specific linkage revelation') ? 430 : 400
+
+          raise InvalidParameterError.new(name, "between 5 and #{max_length} characters") if normalized.length < 5 || normalized.length > max_length
+
+          raise InvalidParameterError.new(name, 'lowercase letters, numbers, and spaces only') unless normalized.match?(/\A[a-z0-9 ]+\z/)
+
+          return unless normalized.include?('  ')
+
+          raise InvalidParameterError.new(name, 'free of consecutive spaces')
+        end
+
+        # Validates a BRC-43 key ID string (1..800 bytes).
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def key_id_string_1_to_800!(name, value)
+          raise InvalidParameterError.new(name, 'a String') unless value.is_a?(String)
+
+          byte_length = value.bytesize
+          raise InvalidParameterError.new(name, 'between 1 and 800 bytes') if byte_length < 1 || byte_length > 800
+        end
+
+        # Validates a wallet counterparty: 'self', 'anyone', or a 66-char hex pubkey.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def wallet_counterparty!(name, value)
+          return if %w[self anyone].include?(value)
+
+          pub_key_hex!(name, value)
+        end
+
+        # Validates a BRC-43 protocol ID: [security_level (0-2), protocol_name (5-400 chars)].
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def wallet_protocol!(name, value)
+          raise InvalidParameterError.new(name, 'an Array of [security_level, protocol_name]') unless value.is_a?(Array) && value.length == 2
+
+          level, proto_name = value
+          raise InvalidParameterError.new(name, 'a security level of 0, 1, or 2') unless [0, 1, 2].include?(level)
+
+          protocol_string_5_to_400!("#{name} protocol name", proto_name)
+        end
+
+        # Validates a certificate acquisition protocol: 'direct' or 'issuance'.
+        #
+        # @param name [String] parameter name for error messages
+        # @param value [Object] the value to validate
+        def acquisition_protocol!(name, value)
+          return if %w[direct issuance].include?(value)
+
+          raise InvalidParameterError.new(name, "'direct' or 'issuance'")
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet/wire.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    module Wire
+      autoload :Frame,        'bsv/wallet/wire/frame'
+      autoload :Calls,        'bsv/wallet/wire/calls'
+      autoload :Validation,   'bsv/wallet/wire/validation'
+      autoload :Writer,       'bsv/wallet/wire/reader_writer'
+      autoload :Reader,       'bsv/wallet/wire/reader_writer'
+    end
+  end
+end

data/lib/bsv/wallet.rb

@@ -8,9 +8,26 @@ module BSV
     require_relative 'wallet/errors'
     require_relative 'wallet/interface'
 
+    # Wire layer — BRC-103 frame codec, call enum, validators, reader/writer.
+    require_relative 'wallet/wire'
+
+    # Per-call BRC-103 serialisers and dispatch tables.
+    autoload :Serializer, 'bsv/wallet/serializer'
+
     # ProtoWallet — minimal crypto-only BRC-100 implementation.
     # Its internals (KeyDeriver, Validators) are scoped under ProtoWallet::
     # to avoid collision with bsv-wallet's own KeyDeriver.
     require_relative 'wallet/proto_wallet'
+
+    # BRC-103 transport layer.
+    autoload :WalletWire,             'bsv/wallet/wallet_wire'
+    autoload :WalletWireTransceiver,  'bsv/wallet/wallet_wire_transceiver'
+    autoload :WalletWireProcessor,    'bsv/wallet/wallet_wire_processor'
+
+    # BRC-103 transport substrates.
+    module Substrates
+      autoload :HTTPWalletWire, 'bsv/wallet/substrates/http_wallet_wire'
+      autoload :HTTPWalletJSON, 'bsv/wallet/substrates/http_wallet_json'
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Simon Bettison
@@ -100,6 +100,7 @@ files:
 - lib/bsv/network/protocol_response.rb
 - lib/bsv/network/protocols.rb
 - lib/bsv/network/protocols/arc.rb
+- lib/bsv/network/protocols/arcade.rb
 - lib/bsv/network/protocols/chaintracks.rb
 - lib/bsv/network/protocols/jungle_bus.rb
 - lib/bsv/network/protocols/ordinals.rb
@@ -110,6 +111,7 @@ files:
 - lib/bsv/network/providers/gorilla_pool.rb
 - lib/bsv/network/providers/taal.rb
 - lib/bsv/network/providers/whats_on_chain.rb
+- lib/bsv/network/util.rb
 - lib/bsv/network/utxo.rb
 - lib/bsv/overlay.rb
 - lib/bsv/overlay/admin_token_template.rb
@@ -171,7 +173,6 @@ files:
 - lib/bsv/transaction/beef.rb
 - lib/bsv/transaction/chain_tracker.rb
 - lib/bsv/transaction/chain_trackers.rb
-- lib/bsv/transaction/chain_trackers/chaintracks.rb
 - lib/bsv/transaction/chain_trackers/whats_on_chain.rb
 - lib/bsv/transaction/fee_model.rb
 - lib/bsv/transaction/fee_models.rb
@@ -194,6 +195,49 @@ files:
 - lib/bsv/wallet/proto_wallet.rb
 - lib/bsv/wallet/proto_wallet/key_deriver.rb
 - lib/bsv/wallet/proto_wallet/validators.rb
+- lib/bsv/wallet/serializer.rb
+- lib/bsv/wallet/serializer/abort_action.rb
+- lib/bsv/wallet/serializer/acquire_certificate.rb
+- lib/bsv/wallet/serializer/certificate.rb
+- lib/bsv/wallet/serializer/common.rb
+- lib/bsv/wallet/serializer/create_action_args.rb
+- lib/bsv/wallet/serializer/create_action_result.rb
+- lib/bsv/wallet/serializer/create_hmac.rb
+- lib/bsv/wallet/serializer/create_signature.rb
+- lib/bsv/wallet/serializer/decrypt.rb
+- lib/bsv/wallet/serializer/discover_by_attributes.rb
+- lib/bsv/wallet/serializer/discover_by_identity_key.rb
+- lib/bsv/wallet/serializer/discover_certificates_result.rb
+- lib/bsv/wallet/serializer/encrypt.rb
+- lib/bsv/wallet/serializer/get_header_for_height.rb
+- lib/bsv/wallet/serializer/get_height.rb
+- lib/bsv/wallet/serializer/get_network.rb
+- lib/bsv/wallet/serializer/get_public_key.rb
+- lib/bsv/wallet/serializer/get_version.rb
+- lib/bsv/wallet/serializer/internalize_action.rb
+- lib/bsv/wallet/serializer/list_actions.rb
+- lib/bsv/wallet/serializer/list_certificates.rb
+- lib/bsv/wallet/serializer/list_outputs.rb
+- lib/bsv/wallet/serializer/prove_certificate.rb
+- lib/bsv/wallet/serializer/relinquish_certificate.rb
+- lib/bsv/wallet/serializer/relinquish_output.rb
+- lib/bsv/wallet/serializer/reveal_counterparty_key_linkage.rb
+- lib/bsv/wallet/serializer/reveal_specific_key_linkage.rb
+- lib/bsv/wallet/serializer/sign_action_args.rb
+- lib/bsv/wallet/serializer/sign_action_result.rb
+- lib/bsv/wallet/serializer/status.rb
+- lib/bsv/wallet/serializer/verify_hmac.rb
+- lib/bsv/wallet/serializer/verify_signature.rb
+- lib/bsv/wallet/substrates/http_wallet_json.rb
+- lib/bsv/wallet/substrates/http_wallet_wire.rb
+- lib/bsv/wallet/wallet_wire.rb
+- lib/bsv/wallet/wallet_wire_processor.rb
+- lib/bsv/wallet/wallet_wire_transceiver.rb
+- lib/bsv/wallet/wire.rb
+- lib/bsv/wallet/wire/calls.rb
+- lib/bsv/wallet/wire/frame.rb
+- lib/bsv/wallet/wire/reader_writer.rb
+- lib/bsv/wallet/wire/validation.rb
 - lib/bsv/wire_format.rb
 homepage: https://github.com/sgbett/bsv-ruby-sdk
 licenses:

data/lib/bsv/transaction/chain_trackers/chaintracks.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-module BSV
-  module Transaction
-    module ChainTrackers
-      # Chain tracker that verifies merkle roots using the Chaintracks API (Arcade/GorillaPool).
-      #
-      # Delegates all HTTP communication to {BSV::Network::Protocols::Chaintracks}.
-      # The constructor signature and {ChainTracker} contract are preserved.
-      #
-      # @example
-      #   tracker = BSV::Transaction::ChainTrackers::Chaintracks.new
-      #   tracker.valid_root_for_height?('abcd...', 800_000)
-      #
-      # @example With API key
-      #   tracker = BSV::Transaction::ChainTrackers::Chaintracks.new(api_key: 'my-key')
-      #   tracker.current_height
-      class Chaintracks < ChainTracker
-        # Returns a Chaintracks instance using the GorillaPool provider default.
-        #
-        # @param testnet [Boolean] when true, uses the testnet endpoint
-        # @param ** [Hash] forwarded to the underlying protocol (e.g. +api_key:+, +http_client:+)
-        # @return [Chaintracks]
-        def self.default(testnet: false, **)
-          provider = BSV::Network::Providers::GorillaPool.default(testnet: testnet, **)
-          protocol = provider.protocol_for(:current_height)
-          new(protocol: protocol)
-        end
-
-        # @param url [String, nil] base URL (legacy compat — prefer .default or protocol:)
-        # @param api_key [String, nil] optional Bearer API key
-        # @param http_client [#request, nil] injectable HTTP client for testing
-        # @param protocol [BSV::Network::Protocols::Chaintracks, nil] pre-configured protocol
-        def initialize(url: nil, api_key: nil, http_client: nil, protocol: nil)
-          super()
-          if protocol
-            @protocol = protocol
-          elsif url
-            @url = url.chomp('/')
-            @api_key = api_key
-            @protocol = BSV::Network::Protocols::Chaintracks.new(
-              base_url: @url,
-              api_key: api_key,
-              http_client: http_client
-            )
-          else
-            provider = BSV::Network::Providers::GorillaPool.default(api_key: api_key, http_client: http_client)
-            @protocol = provider.protocol_for(:current_height)
-          end
-        end
-
-        # Verify that a merkle root is valid for the given block height.
-        #
-        # @param root [String] merkle root as a hex string
-        # @param height [Integer] block height
-        # @return [Boolean]
-        # @raise [StandardError] on network or API error
-        def valid_root_for_height?(root, height)
-          result = @protocol.call(:get_block_header, height)
-          return false if result.http_not_found?
-
-          raise result.message.to_s unless result.http_success?
-
-          merkle_root = result.data['merkleRoot']
-          return false unless merkle_root
-
-          merkle_root.downcase == root.downcase
-        end
-
-        # Return the current blockchain height.
-        #
-        # @return [Integer]
-        # @raise [StandardError] on network or API error
-        def current_height
-          result = @protocol.call(:current_height)
-          return result.data if result.http_success?
-
-          raise result.message.to_s
-        end
-      end
-    end
-  end
-end