bsv-sdk 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9924711798c6f50752254b528fb1956bcc39e3cf5cf1b57fdf94a887a3dc9688
-  data.tar.gz: d3cd183e1ccdafadbe37b989275cd03d4c505e2432b3ede6d1af5213b7455361
+  metadata.gz: 5d32b117209fc6509e5020811725c5b5bb5e776c57fbd0f3cb0afa8cf3cc12ca
+  data.tar.gz: 2fa913c8e3fe270b53a1748e2ff4bdb8055945b625a9e3075eb293b78d581fe4
 SHA512:
-  metadata.gz: 88f3ed7869e81aec560b47a405e9144d00e3e48cf4b62d5be6bd09e58ac216ebbe8b56ebcff2ac61075c901d56308875b7ff4673d2e066df74f723e6391f3ea5
-  data.tar.gz: a88d52282aa5d2a05b906685245b6690c434dbea73fb01ed99be1dc93a4706720c13ee5fb48830a4c3c423c9160db264fe66c910de5995c94047f61e7f56120d
+  metadata.gz: 82e8ca0cf9e266d7c80fe8be42be40450e5a3495db083f90aa098aaf7ff0186ecc4a63b3a1efd9b7447738d857b930f655be291ad098a83ef7a6d0095df0b4d0
+  data.tar.gz: 103b3246361a57c3b1161c789c097c147b6c7070781094587f59bdee6caf3141bb5b22934a89e1bfdd4e514b4f45eb2edd1ae218fc92f23e2d520a3a56f72113

data/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-04-01
+
+### Added
+
+#### Primitives
+
+- **Bitcore ECIES** — `ECIES.bitcore_encrypt` / `ECIES.bitcore_decrypt`. AES-256-CBC with random IV, SHA-512(X-coordinate) key derivation. Matches ts-sdk and go-sdk Bitcore variants.
+
+#### Transaction
+
+- **LivePolicy.default** — one-line convenience for live fee queries via GorillaPool ARC with 5-minute cache and 100 sat/kB fallback.
+
+### Changed
+
+- **Default fee rate**: `SatoshisPerKilobyte` default changed from 50 to 100 sat/kB (matches ts-sdk LivePolicy fallback). `Wallet#fund` default changed from 0.5 to 0.1 sat/byte.
+
+### bsv-wallet v0.2.0
+
+- **FileStore** — JSON file-backed persistent storage, now the default for `WalletClient`. Data survives process restarts. MemoryStore becomes explicit opt-in for tests.
+- **File permissions** — directory created with 0700, files with 0600. Warns via Logger on startup if permissions are too open.
+- **BRC-31 Auth/Peer** — mutual authentication with nonce-based challenges, ECDSA signatures, and session management.
+- **Wire protocol** — binary ABI serialisation for all 28 BRC-100 methods (call codes 1-28, VarInt encoding).
+- **Certificate issuance** — `acquire_certificate` with `'issuance'` protocol (POST to certifier URL).
+- **OpCat template** — OP_CAT concatenation script template with lock/unlock constructors.
+- **Live fee policy** — `LivePolicy` fee model fetching from ARC `/v1/policy`.
+
+### Fixed
+
+- Subject and certifier pinned in certificate issuance response (not overridable by remote certifier)
+- Wire reader negative privileged_reason length crash
+- PUSHDATA1/2/4 bounds check (silent data corruption on truncated scripts)
+- Extended key path validation (reject non-numeric indices)
+
+## [0.3.0] - 2026-03-27
+
+### Added
+
+#### Primitives
+
+- **SymmetricKey** — AES-256-GCM encryption/decryption with 32-byte IV (cross-SDK compatible). Construct from random, ECDH, or raw bytes.
+- **BRC-77 SignedMessage** — authenticated message signing and verification using BRC-42 derived keys. Supports targeted (specific verifier) and "anyone" modes.
+- **BRC-78 EncryptedMessage** — end-to-end encrypted messaging using ECDH-derived symmetric keys.
+- **Schnorr ZKP (BRC-94)** — zero-knowledge proof of ECDH shared secret knowledge. `Schnorr.generate_proof` / `Schnorr.verify_proof`.
+- **Shamir's Secret Sharing** — split private keys into threshold shares (`PrivateKey#to_key_shares`) with Lagrange interpolation reconstruction. Backup format with integrity check.
+
+#### Script
+
+- **PushDrop template** — data carrier with P2PK spending. `Script.pushdrop_lock` / `Script.pushdrop_unlock` with field extraction.
+- **RPuzzle template** — R-puzzle hash-based spending with 6 hash type variants (raw, SHA1, SHA256, RIPEMD160, HASH160, HASH256).
+
+#### Transaction
+
+- **Benford's law change distribution** — privacy-preserving change output splitting using Benford's first-digit distribution.
+- **ARC X-WaitFor** — `ARC#broadcast` gains `wait_for:` parameter for `X-WaitFor` header (RECEIVED, STORED, ANNOUNCED_TO_NETWORK, SEEN_ON_NETWORK, MINED).
+
+### Fixed
+
+- Empty plaintext/ciphertext handling on older OpenSSL versions
+- PushDrop detection for minimally-encoded fields
+
+### Changed
+
+- `Transaction#fee` change distribution uses Benford's law (was equal split)
+- `LineLength` raised to 150
+
 ## [0.2.1] - 2026-03-07
 
 ### Fixed

data/lib/bsv/primitives/ecies.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'openssl'
+require 'securerandom'
 
 module BSV
   module Primitives
@@ -95,6 +96,74 @@ module BSV
         end
       end
 
+      # Encrypt a message using the Bitcore ECIES variant.
+      #
+      # Differs from the Electrum variant: no magic prefix, AES-256-CBC
+      # (not AES-128), random IV prepended to ciphertext, and HMAC covers
+      # the ciphertext (not the ephemeral pubkey).
+      #
+      # Wire format: +ephemeral_pub(33) + IV(16) + ciphertext + HMAC(32)+
+      #
+      # @param message [String] the plaintext message
+      # @param public_key [PublicKey] the recipient's public key
+      # @param private_key [PrivateKey, nil] optional ephemeral key (random if omitted)
+      # @return [String] encrypted payload
+      def bitcore_encrypt(message, public_key, private_key: nil)
+        message = message.b if message.encoding != Encoding::ASCII_8BIT
+
+        ephemeral = private_key || PrivateKey.generate
+        key_e, key_m = derive_bitcore_keys(ephemeral, public_key)
+
+        iv = SecureRandom.random_bytes(16)
+
+        cipher = OpenSSL::Cipher.new('aes-256-cbc')
+        cipher.encrypt
+        cipher.key = key_e
+        cipher.iv = iv
+        ciphertext = message.empty? ? cipher.final : cipher.update(message) + cipher.final
+
+        c = iv + ciphertext
+        mac = Digest.hmac_sha256(key_m, c)
+
+        ephemeral.public_key.compressed + c + mac
+      end
+
+      # Decrypt a message encrypted with the Bitcore ECIES variant.
+      #
+      # @param data [String] the encrypted payload (Bitcore ECIES format)
+      # @param private_key [PrivateKey] the recipient's private key
+      # @return [String] the decrypted plaintext
+      # @raise [ArgumentError] if the data is too short
+      # @raise [DecryptionError] if HMAC verification or AES decryption fails
+      def bitcore_decrypt(data, private_key)
+        data = data.b if data.encoding != Encoding::ASCII_8BIT
+
+        # Minimum: ephemeral_pub(33) + IV(16) + AES block(16) + HMAC(32) = 97
+        raise ArgumentError, 'data too short' if data.bytesize < 97
+
+        ephemeral_pub = PublicKey.from_bytes(data[0, 33])
+        mac = data[-32, 32]
+        c = data[33...-32] # IV + ciphertext
+
+        key_e, key_m = derive_bitcore_keys(private_key, ephemeral_pub)
+
+        expected_mac = Digest.hmac_sha256(key_m, c)
+        raise DecryptionError, 'HMAC verification failed' unless secure_compare(mac, expected_mac)
+
+        iv = c[0, 16]
+        ciphertext = c[16..]
+
+        begin
+          cipher = OpenSSL::Cipher.new('aes-256-cbc')
+          cipher.decrypt
+          cipher.key = key_e
+          cipher.iv = iv
+          cipher.update(ciphertext) + cipher.final
+        rescue OpenSSL::Cipher::CipherError => e
+          raise DecryptionError, "decryption failed: #{e.message}"
+        end
+      end
+
       class << self
         private
 
@@ -122,6 +191,19 @@ module BSV
 
           [iv, key_e, key_m]
         end
+
+        # Bitcore key derivation: SHA-512(ECDH X-coordinate) → key_e(32) + key_m(32)
+        def derive_bitcore_keys(private_key, public_key)
+          shared = private_key.derive_shared_secret(public_key)
+          # Bitcore uses raw X-coordinate (32 bytes BE), not compressed point
+          x_bytes = shared.point.to_octet_string(:uncompressed)[1, 32]
+          derived = Digest.sha512(x_bytes)
+
+          key_e = derived[0, 32]
+          key_m = derived[32, 32]
+
+          [key_e, key_m]
+        end
       end
     end
   end

data/lib/bsv/transaction/fee_models/live_policy.rb

@@ -32,12 +32,24 @@ module BSV
         # @return [Integer] cache TTL in seconds
         attr_reader :cache_ttl
 
+        DEFAULT_ARC_URL = 'https://arc.gorillapool.io'
+        DEFAULT_FALLBACK_RATE = 100
+
+        # Returns a LivePolicy with sensible defaults (GorillaPool ARC,
+        # 100 sat/kB fallback, 5-minute cache).
+        #
+        # @param api_key [String, nil] optional ARC API key
+        # @return [LivePolicy]
+        def self.default(api_key: nil)
+          new(arc_url: DEFAULT_ARC_URL, fallback_rate: DEFAULT_FALLBACK_RATE, api_key: api_key)
+        end
+
         # @param arc_url [String] ARC base URL (e.g. 'https://arc.gorillapool.io')
-        # @param fallback_rate [Integer] sat/kB to use when fetch fails (default: 50)
+        # @param fallback_rate [Integer] sat/kB to use when fetch fails (default: 100)
         # @param cache_ttl [Integer] seconds to cache a fetched rate (default: 300)
         # @param api_key [String, nil] optional Bearer token for ARC authentication
         # @param http_client [#request, nil] injectable HTTP client for testing
-        def initialize(arc_url:, fallback_rate: 50, cache_ttl: DEFAULT_CACHE_TTL, api_key: nil, http_client: nil)
+        def initialize(arc_url:, fallback_rate: DEFAULT_FALLBACK_RATE, cache_ttl: DEFAULT_CACHE_TTL, api_key: nil, http_client: nil)
           super()
           @arc_url = arc_url.chomp('/')
           @fallback_rate = fallback_rate

data/lib/bsv/transaction/fee_models/satoshis_per_kilobyte.rb

@@ -15,8 +15,8 @@ module BSV
         # @return [Integer] satoshis per kilobyte rate
         attr_reader :value
 
-        # @param value [Integer] satoshis per kilobyte (default: 50)
-        def initialize(value: 50)
+        # @param value [Integer] satoshis per kilobyte (default: 100)
+        def initialize(value: 100)
           super()
           @value = value
         end

data/lib/bsv/version.rb

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

data/lib/bsv/wallet/wallet.rb

@@ -25,7 +25,7 @@ module BSV
         @provider.fetch_utxos(address(network: network)).sum(&:satoshis)
       end
 
-      def fund(tx, network: :mainnet, satoshis_per_byte: 0.5)
+      def fund(tx, network: :mainnet, satoshis_per_byte: 0.1)
         utxos = @provider.fetch_utxos(address(network: network))
         output_total = tx.total_output_satoshis
 
@@ -66,7 +66,7 @@ module BSV
         tx.sign_all(@private_key)
       end
 
-      def fund_and_sign(tx, network: :mainnet, satoshis_per_byte: 0.5)
+      def fund_and_sign(tx, network: :mainnet, satoshis_per_byte: 0.1)
         fund(tx, network: network, satoshis_per_byte: satoshis_per_byte)
         sign(tx)
       end

data/lib/bsv/wallet_interface/file_store.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'logger'
+
+module BSV
+  module Wallet
+    # JSON file-backed storage adapter.
+    #
+    # Persists actions, outputs, and certificates as JSON files in a
+    # configurable directory (default: +~/.bsv-wallet/+). Data survives
+    # process restarts.
+    #
+    # Inherits all filtering and pagination logic from {MemoryStore} and
+    # adds load-on-init / save-on-mutation.
+    #
+    # @example Default location
+    #   store = BSV::Wallet::FileStore.new
+    #   # Data written to ~/.bsv-wallet/
+    #
+    # @example Custom directory
+    #   store = BSV::Wallet::FileStore.new(dir: '/var/lib/my-app/wallet')
+    class FileStore < MemoryStore
+      DEFAULT_DIR = File.expand_path('~/.bsv-wallet')
+
+      # @param dir [String] directory for JSON files
+      #   (default: +~/.bsv-wallet/+ or +BSV_WALLET_DIR+ env var)
+      # @param dir [String] directory for JSON files
+      # @param logger [Logger, nil] logger for permission warnings (default: Logger to STDERR)
+      def initialize(dir: nil, logger: nil)
+        super()
+        @dir = dir || ENV.fetch('BSV_WALLET_DIR', DEFAULT_DIR)
+        @logger = logger || Logger.new($stderr, progname: 'bsv-wallet')
+        FileUtils.mkdir_p(@dir, mode: 0o700)
+        check_permissions
+        load_from_disk
+      end
+
+      # @return [String] the storage directory path
+      attr_reader :dir
+
+      # --- Mutations: delegate to super, then persist ---
+
+      def store_action(action_data)
+        result = super
+        save_actions
+        result
+      end
+
+      def store_output(output_data)
+        result = super
+        save_outputs
+        result
+      end
+
+      def delete_output(outpoint)
+        result = super
+        save_outputs if result
+        result
+      end
+
+      def store_certificate(cert_data)
+        result = super
+        save_certificates
+        result
+      end
+
+      def delete_certificate(type:, serial_number:, certifier:)
+        result = super
+        save_certificates if result
+        result
+      end
+
+      private
+
+      def check_permissions
+        dir_mode = File.stat(@dir).mode & 0o777
+        if dir_mode != 0o700
+          @logger.warn("Wallet directory #{@dir} has permissions #{format('%04o', dir_mode)} (expected 0700). " \
+                       'Other users may be able to access wallet data.')
+        end
+
+        [actions_path, outputs_path, certificates_path].each do |path|
+          next unless File.exist?(path)
+
+          file_mode = File.stat(path).mode & 0o777
+          next if file_mode == 0o600
+
+          @logger.warn("Wallet file #{path} has permissions #{format('%04o', file_mode)} (expected 0600). " \
+                       'Other users may be able to read wallet data.')
+        end
+      end
+
+      def actions_path
+        File.join(@dir, 'actions.json')
+      end
+
+      def outputs_path
+        File.join(@dir, 'outputs.json')
+      end
+
+      def certificates_path
+        File.join(@dir, 'certificates.json')
+      end
+
+      def load_from_disk
+        @actions = load_file(actions_path)
+        @outputs = load_file(outputs_path)
+        @certificates = load_file(certificates_path)
+      end
+
+      def load_file(path)
+        return [] unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        return [] unless data.is_a?(Array)
+
+        # Symbolise top-level keys for consistency with MemoryStore
+        data.map { |entry| symbolise_keys(entry) }
+      rescue JSON::ParserError
+        []
+      end
+
+      def save_actions
+        write_file(actions_path, @actions)
+      end
+
+      def save_outputs
+        write_file(outputs_path, @outputs)
+      end
+
+      def save_certificates
+        write_file(certificates_path, @certificates)
+      end
+
+      def write_file(path, data)
+        json = JSON.pretty_generate(stringify_keys_deep(data))
+        tmp = "#{path}.tmp"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(json) }
+        File.rename(tmp, path)
+      end
+
+      def symbolise_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(k, v), result|
+          result[k.to_sym] = case v
+                             when Hash then symbolise_keys(v)
+                             when Array then v.map { |e| e.is_a?(Hash) ? symbolise_keys(e) : e }
+                             else v
+                             end
+        end
+      end
+
+      def stringify_keys_deep(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), result|
+            result[k.to_s] = stringify_keys_deep(v)
+          end
+        when Array
+          obj.map { |e| stringify_keys_deep(e) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.1.2'
+    VERSION = '0.2.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -36,11 +36,12 @@ module BSV
       attr_reader :network
 
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
-      # @param storage [StorageAdapter] persistence adapter (default: MemoryStore)
+      # @param storage [StorageAdapter] persistence adapter (default: FileStore).
+      #   Use +storage: MemoryStore.new+ for tests.
       # @param network [String] 'mainnet' (default) or 'testnet'
       # @param chain_provider [ChainProvider] blockchain data provider (default: NullChainProvider)
       # @param http_client [#request, nil] injectable HTTP client for certificate issuance
-      def initialize(key, storage: MemoryStore.new, network: 'mainnet', chain_provider: NullChainProvider.new, http_client: nil)
+      def initialize(key, storage: FileStore.new, network: 'mainnet', chain_provider: NullChainProvider.new, http_client: nil)
         super(key)
         @storage = storage
         @network = network

data/lib/bsv/wallet_interface.rb

@@ -13,6 +13,7 @@ module BSV
     autoload :Validators,       'bsv/wallet_interface/validators'
     autoload :StorageAdapter,    'bsv/wallet_interface/storage_adapter'
     autoload :MemoryStore,       'bsv/wallet_interface/memory_store'
+    autoload :FileStore,         'bsv/wallet_interface/file_store'
     autoload :ChainProvider,     'bsv/wallet_interface/chain_provider'
     autoload :NullChainProvider, 'bsv/wallet_interface/null_chain_provider'
     autoload :WalletClient,      'bsv/wallet_interface/wallet_client'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby library for interacting with the BSV Blockchain — keys, scripts,
   transactions, and more.
@@ -105,6 +105,7 @@ files:
 - lib/bsv/wallet_interface/errors/invalid_signature_error.rb
 - lib/bsv/wallet_interface/errors/unsupported_action_error.rb
 - lib/bsv/wallet_interface/errors/wallet_error.rb
+- lib/bsv/wallet_interface/file_store.rb
 - lib/bsv/wallet_interface/interface.rb
 - lib/bsv/wallet_interface/key_deriver.rb
 - lib/bsv/wallet_interface/memory_store.rb