bsv-sdk 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4947a18f171b512f9504b7f43b9e53867f72e221f3408db8f7c5d93f4cd7878c
-  data.tar.gz: a282778766358b1b0fe8c8184ecab5132548ec7a68d48989712ffd906b00c2a6
+  metadata.gz: 264bf278568bb64d32cd8445708f29436478c0b9a2bee01e74a71a00549e46f9
+  data.tar.gz: 0a29a5a53bac041332971c8a51628289ced3606423b4f02777780eac7171eeeb
 SHA512:
-  metadata.gz: c70124fbf7d8044af528f1e927da94fe1c0661d35e09053e10ae934d83d5f808ec7fc612891d95e2faae2ee76c15e5355c2ae27b15cacbf29bec7ae911ff6244
-  data.tar.gz: de507490b32cd0bc3dc494410a3a0637af2c32620bcd704ffcd285bc479b4c28f15e8304af59f4d907deb01234f8ffc6b6cea1d87baec4f8c358f0214595c3bb
+  metadata.gz: fa512a05a6afb7099c94c55a54524623ab0706fddc4b7836315f4750e6ad69abc438581aea4707e1ae6e93b23437868960a7c2bbfca8b86848d676cd587bbd7b
+  data.tar.gz: 35d2b3175fa5c5c65a200756e7c9abb64166b44fc370cac38ecb29a8faefdba641de60a07cdb2d9f3d12a695784b09eea8ba12b502865222073fdfe171251b91

data/{CHANGELOG-sdk.md → CHANGELOG.md}

@@ -5,6 +5,43 @@ All notable changes to the `bsv-sdk` 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.10.0 — 2026-04-11
+
+### Added
+
+- **Chronicle opcode support** (HLR #328). All 10 Chronicle-restored opcodes
+  now execute with correct semantics, replacing the 0.9.0 "raise first"
+  fail-safes:
+  - **Splice:** OP_SUBSTR, OP_LEFT, OP_RIGHT
+  - **Arithmetic:** OP_LSHIFTNUM, OP_RSHIFTNUM (sign-preserving right shift)
+  - **Arithmetic:** OP_2MUL, OP_2DIV (restored from disabled)
+  - **Flow control:** OP_VER (push 4-byte LE tx version), OP_VERIF/OP_VERNOTIF
+    (version-conditional branching, added to CONDITIONAL_OPCODES)
+  - `MISSING_TX_CONTEXT` error code for OP_VER without transaction context
+
+- **Arcade integration** (HLR #329):
+  - `BSV::Transaction::ChainTrackers::Chaintracks` — chain tracker using
+    Arcade's Chaintracks v2 API for SPV verification
+  - `ChainTrackers.default(testnet:)` — factory returning a Chaintracks
+    instance pointed at Arcade
+  - `ARC.default(testnet:)` — factory returning an ARC broadcaster pointed
+    at GorillaPool, matching TS/Go/Py SDK defaults
+  - `ARC#broadcast_many(txs)` — batch broadcast via POST `/v1/txs`, returns
+    mixed array of `BroadcastResponse`/`BroadcastError`
+  - Skip-validation headers (`skip_fee_validation:`, `skip_script_validation:`)
+    on `broadcast` and `broadcast_many`
+
+### Changed
+
+- **Directory restructure** (PR #327). Source files moved to per-gem
+  directories: `gem/bsv-sdk/`, `gem/bsv-wallet/`, `gem/bsv-attest/`.
+  No change to gem names or require paths.
+
+### Removed
+
+- **`op_disabled` handler** — OP_2MUL/OP_2DIV are now restored; the handler
+  is no longer needed.
+
 ## 0.9.0 — 2026-04-10
 
 ### Changed

data/bin/bsv-mcp

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# MCP stdio protocol: stdout is the JSON-RPC channel — do not write to it.
+# All diagnostic output must use $stderr (warn, $stderr.puts, etc.).
+
+require_relative '../lib/bsv-sdk'
+
+config = BSV::MCP::Config.new
+BSV::MCP::Server.start(config)

data/lib/bsv/mcp/config.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    # Configuration parsed from environment variables for the MCP server.
+    #
+    # Environment variables:
+    #   BSV_NETWORK   — 'mainnet' or 'testnet' (default: 'mainnet')
+    #   BSV_ARC_URL   — optional ARC endpoint override
+    #   BSV_ARC_API_KEY — optional ARC bearer token
+    class Config
+      MAINNET = 'mainnet'
+      TESTNET = 'testnet'
+      VALID_NETWORKS = [MAINNET, TESTNET].freeze
+
+      attr_reader :network, :arc_url, :arc_api_key
+
+      def initialize(network: nil, arc_url: nil, arc_api_key: nil)
+        raw_network = network || ENV.fetch('BSV_NETWORK', MAINNET)
+        @network = normalise_network(raw_network)
+        @arc_url = arc_url || ENV.fetch('BSV_ARC_URL', nil)
+        @arc_api_key = arc_api_key || ENV.fetch('BSV_ARC_API_KEY', nil)
+      end
+
+      def mainnet?
+        @network == MAINNET
+      end
+
+      def testnet?
+        @network == TESTNET
+      end
+
+      private
+
+      def normalise_network(value)
+        normalised = value.to_s.strip.downcase
+        return normalised if VALID_NETWORKS.include?(normalised)
+
+        warn "BSV::MCP::Config: unknown network '#{value}', defaulting to '#{MAINNET}'"
+        MAINNET
+      end
+    end
+  end
+end

data/lib/bsv/mcp/server.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+module BSV
+  module MCP
+    # Builds and returns an MCP::Server instance configured for the BSV SDK.
+    #
+    # Tools are registered here as the feature set grows. Currently returns an
+    # empty tool list — Tasks 2 and 3 will add concrete tools.
+    #
+    # Logging goes to $stderr only; $stdout is the MCP protocol channel.
+    module Server
+      # Builds the MCP::Server instance with the given config.
+      #
+      # @param config [BSV::MCP::Config] network and ARC configuration
+      # @return [::MCP::Server]
+      def self.build(config = nil)
+        config ||= Config.new
+
+        ::MCP::Server.new(
+          name: 'bsv-sdk',
+          version: BSV::VERSION,
+          instructions: server_instructions(config),
+          tools: registered_tools
+        )
+      end
+
+      # Returns the list of tool classes registered with this server.
+      #
+      # @return [Array<Class>] tool classes inheriting from MCP::Tool
+      def self.registered_tools
+        [
+          Tools::GenerateKey,
+          Tools::DecodeTx,
+          Tools::FetchUtxos,
+          Tools::FetchTx,
+          Tools::CheckBalance,
+          Tools::BroadcastP2pkh
+        ]
+      end
+
+      # Starts the MCP server over stdio using the standard StdioTransport.
+      # Blocks until the client disconnects or the process is interrupted.
+      #
+      # @param config [BSV::MCP::Config] network and ARC configuration
+      def self.start(config = nil)
+        config ||= Config.new
+
+        warn "BSV MCP server starting (network: #{config.network}, version: #{BSV::VERSION})"
+
+        server = build(config)
+        transport = ::MCP::Server::Transports::StdioTransport.new(server)
+        transport.open
+      end
+
+      # @api private
+      def self.server_instructions(config)
+        <<~INSTRUCTIONS.strip
+          BSV blockchain SDK tools. Network: #{config.network}.
+          All operations target the #{config.network} network unless otherwise noted.
+          Keys are passed as WIF strings and are never persisted by the server.
+        INSTRUCTIONS
+      end
+      private_class_method :server_instructions
+    end
+  end
+end

data/lib/bsv/mcp/tools/broadcast_p2pkh.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Builds, signs, and broadcasts a simple P2PKH payment transaction.
+      #
+      # Fetches UTXOs for the sender's address, constructs a transaction
+      # with one payment output and one change output, signs all inputs
+      # with the provided private key, and submits to ARC in Extended
+      # Format (EF/BRC-30).
+      #
+      # This is the most complex MCP tool: it orchestrates WIF → PrivateKey
+      # → PublicKey → address → UTXO fetch → tx build → sign → broadcast.
+      class BroadcastP2pkh < ::MCP::Tool
+        tool_name 'broadcast_p2pkh'
+
+        description <<~DESC.strip
+          Build, sign, and broadcast a P2PKH payment transaction.
+
+          WARNING: This tool broadcasts a REAL transaction to the BSV network
+          and SPENDS REAL SATOSHIS. Use testnet for testing.
+
+          The tool:
+          1. Derives the sender address from the WIF private key
+          2. Fetches UTXOs for the sender address via WhatsOnChain
+          3. Selects sufficient UTXOs (greedy: largest first)
+          4. Builds a transaction with a payment output and a change output
+          5. Signs all inputs with the WIF key (P2PKH, SIGHASH_ALL|FORKID)
+          6. Submits to ARC in Extended Format (EF/BRC-30)
+          7. Returns txid, status, and the raw hex
+
+          Parameters:
+          - wif: sender's private key in WIF format. The key is used only
+            for this call and is never stored by the server.
+          - to_address: recipient P2PKH address
+          - satoshis: amount to send in satoshis (must be > 0)
+          - network: 'mainnet' or 'testnet' — overrides the server default
+
+          Returns:
+          - txid: the broadcast transaction ID
+          - tx_status: ARC status string (e.g. 'SEEN_ON_NETWORK')
+          - hex: the raw transaction hex (plain format, not EF)
+
+          Error conditions (returned as error responses, not raised):
+          - Invalid WIF key
+          - No UTXOs found for sender
+          - Insufficient funds (balance < satoshis + estimated fee)
+          - Change below dust (546 sat): change is absorbed into the fee
+          - ARC broadcast rejection
+
+          Technical notes:
+          - All inputs have source_satoshis and source_locking_script set,
+            enabling Extended Format (EF/BRC-30) submission to ARC.
+          - Fee model: SatoshisPerKilobyte at 100 sat/kB (SDK default).
+          - Change returns to the sender address.
+          - UTXO selection: greedy descending by value.
+        DESC
+
+        input_schema(
+          type: 'object',
+          properties: {
+            wif: {
+              type: 'string',
+              description: 'Sender private key in WIF format.'
+            },
+            to_address: {
+              type: 'string',
+              description: 'Recipient P2PKH address.'
+            },
+            satoshis: {
+              type: 'integer',
+              description: 'Amount to send in satoshis.',
+              minimum: 1
+            },
+            network: {
+              type: 'string',
+              enum: %w[mainnet testnet],
+              description: 'Network to broadcast on. Overrides the server default.'
+            }
+          },
+          required: %w[wif to_address satoshis]
+        )
+
+        # Minimum output value to avoid dust rejection.
+        DUST_THRESHOLD = 546
+
+        def self.call(wif:, to_address:, satoshis:, network: nil, server_context: nil)
+          net_sym = Helpers.resolve_network_sym(network, server_context)
+
+          private_key = BSV::Primitives::PrivateKey.from_wif(wif)
+          sender_address = private_key.public_key.address(network: net_sym)
+
+          woc = BSV::Network::WhatsOnChain.new(network: net_sym)
+          all_utxos = woc.fetch_utxos(sender_address)
+
+          return Helpers.error_response('No UTXOs found for sender address — the address may have no funds') if all_utxos.empty?
+
+          # Greedy UTXO selection: sort descending, take until sufficient
+          sorted = all_utxos.sort_by { |u| -u.satoshis }
+          selected = select_utxos(sorted, satoshis)
+          return Helpers.error_response("Insufficient funds — available: #{all_utxos.sum(&:satoshis)} satoshis") if selected.nil?
+
+          tx = build_transaction(selected, satoshis, to_address, sender_address, private_key)
+
+          arc = build_arc(net_sym, server_context)
+          broadcast_result = arc.broadcast(tx)
+
+          result = {
+            txid: broadcast_result.txid,
+            tx_status: broadcast_result.tx_status,
+            hex: tx.to_hex
+          }
+
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(result.to_json)],
+            structured_content: result
+          )
+        rescue ArgumentError => e
+          Helpers.error_response(e.message)
+        rescue BSV::Network::ChainProviderError => e
+          Helpers.error_response("UTXO fetch failed: #{e.message}")
+        rescue BSV::Network::BroadcastError => e
+          Helpers.error_response("Broadcast failed: #{e.message}")
+        end
+
+        # Select UTXOs greedily until the total meets or exceeds the target.
+        # Returns nil when total funds are insufficient.
+        # @api private
+        def self.select_utxos(sorted_utxos, target_satoshis)
+          selected = []
+          total = 0
+          sorted_utxos.each do |utxo|
+            selected << utxo
+            total += utxo.satoshis
+            break if total >= target_satoshis
+          end
+          # We may still not have enough — caller checks nil return
+          total >= target_satoshis ? selected : nil
+        end
+        private_class_method :select_utxos
+
+        # Build, fee-compute, and sign the transaction.
+        # @api private
+        def self.build_transaction(selected_utxos, satoshis, to_address, sender_address, private_key)
+          tx = BSV::Transaction::Transaction.new
+
+          # Wire inputs with EF metadata (source_satoshis + source_locking_script)
+          selected_utxos.each do |utxo|
+            locking_script = p2pkh_lock_for(sender_address)
+            input = BSV::Transaction::TransactionInput.new(
+              prev_tx_id: BSV::Transaction::TransactionInput.txid_from_hex(utxo.tx_hash),
+              prev_tx_out_index: utxo.tx_pos
+            )
+            input.source_satoshis = utxo.satoshis
+            input.source_locking_script = locking_script
+            input.unlocking_script_template = BSV::Transaction::P2PKH.new(private_key)
+            tx.add_input(input)
+          end
+
+          # Payment output
+          tx.add_output(BSV::Transaction::TransactionOutput.new(
+                          satoshis: satoshis,
+                          locking_script: p2pkh_lock_for(to_address)
+                        ))
+
+          # Change output (marked as change so tx.fee distributes into it)
+          tx.add_output(BSV::Transaction::TransactionOutput.new(
+                          satoshis: 0,
+                          locking_script: p2pkh_lock_for(sender_address),
+                          change: true
+                        ))
+
+          # Compute fee and distribute change; removes change output when dust
+          tx.fee
+
+          # Guard: if total outputs exceed inputs the transaction is invalid
+          if tx.total_output_satoshis > tx.total_input_satoshis
+            raise ArgumentError,
+                  "Insufficient funds: inputs #{tx.total_input_satoshis} sat, " \
+                  "outputs #{tx.total_output_satoshis} sat (including fee)"
+          end
+
+          # Sign all inputs via their P2PKH templates
+          tx.sign_all
+
+          tx
+        end
+        private_class_method :build_transaction
+
+        # Build a P2PKH locking script for the given address.
+        # @api private
+        def self.p2pkh_lock_for(address)
+          hash160 = BSV::Primitives::Base58.check_decode(address)[1..]
+          BSV::Script::Script.p2pkh_lock(hash160)
+        end
+        private_class_method :p2pkh_lock_for
+
+        # Build an ARC broadcaster using server config when available.
+        # @api private
+        def self.build_arc(net_sym, server_context)
+          testnet = net_sym == :testnet
+          opts = {}
+          opts[:api_key] = server_context[:arc_api_key] if server_context.is_a?(Hash) && server_context[:arc_api_key]
+          BSV::Network::ARC.default(testnet: testnet, **opts)
+        end
+        private_class_method :build_arc
+      end
+    end
+  end
+end

data/lib/bsv/mcp/tools/check_balance.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Returns the total confirmed and unconfirmed balance for a BSV address
+      # or WIF private key, along with the individual UTXOs.
+      #
+      # Accepts either a WIF-encoded private key (from which the address is
+      # derived) or a plain P2PKH address string. The tool auto-detects the
+      # input type via a try/rescue on +PrivateKey.from_wif+.
+      class CheckBalance < ::MCP::Tool
+        tool_name 'check_balance'
+
+        description <<~DESC.strip
+          Check the BSV balance for an address or WIF private key.
+
+          Accepts either a WIF-encoded private key (auto-derives the address)
+          or a P2PKH address string directly. The tool detects which was
+          supplied automatically.
+
+          Parameters:
+          - address_or_wif: a BSV P2PKH address (mainnet starts with '1';
+            testnet starts with 'm' or 'n') OR a WIF private key (mainnet
+            starts with '5', 'K', or 'L'; testnet starts with '9' or 'c')
+          - network: 'mainnet' or 'testnet' — overrides the server default
+
+          Returns:
+          - address: the resolved P2PKH address
+          - balance_satoshis: total balance across all UTXOs
+          - utxo_count: number of unspent outputs
+          - utxos: array of { tx_hash, tx_pos, satoshis, height } objects
+
+          Note: balance is the sum of all UTXOs; it does not distinguish
+          confirmed from unconfirmed. A height of 0 indicates an unconfirmed
+          (mempool) UTXO.
+
+          Note: addresses are network-specific. A mainnet address queried
+          against testnet (or vice versa) will return no results or an error.
+        DESC
+
+        input_schema(
+          type: 'object',
+          properties: {
+            address_or_wif: {
+              type: 'string',
+              description: 'BSV P2PKH address or WIF private key to check.'
+            },
+            network: {
+              type: 'string',
+              enum: %w[mainnet testnet],
+              description: 'Network to query. Overrides the server default.'
+            }
+          },
+          required: ['address_or_wif']
+        )
+
+        def self.call(address_or_wif:, network: nil, server_context: nil)
+          net_sym = Helpers.resolve_network_sym(network, server_context)
+          address = resolve_address(address_or_wif, net_sym)
+
+          woc = BSV::Network::WhatsOnChain.new(network: net_sym)
+          utxos = woc.fetch_utxos(address)
+
+          balance = utxos.sum(&:satoshis)
+          result = {
+            address: address,
+            network: net_sym.to_s,
+            balance_satoshis: balance,
+            utxo_count: utxos.length,
+            utxos: utxos.map { |u| Helpers.utxo_to_h(u) }
+          }
+
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(result.to_json)],
+            structured_content: result
+          )
+        rescue ArgumentError => e
+          Helpers.error_response(e.message)
+        rescue BSV::Network::ChainProviderError => e
+          Helpers.error_response("#{e.message} (HTTP #{e.status_code})")
+        end
+
+        # Resolve a WIF key or address string to a P2PKH address.
+        # @api private
+        def self.resolve_address(address_or_wif, net_sym)
+          key = BSV::Primitives::PrivateKey.from_wif(address_or_wif)
+          key.public_key.address(network: net_sym)
+        rescue ArgumentError
+          address_or_wif
+        end
+        private_class_method :resolve_address
+      end
+    end
+  end
+end

data/lib/bsv/mcp/tools/decode_tx.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Decodes a raw BSV transaction from hex and returns a structured
+      # human-readable representation.
+      #
+      # Supports standard raw hex only (not BEEF format). The txid is
+      # returned in display byte order (reversed from the wire hash),
+      # matching block explorer conventions.
+      class DecodeTx < ::MCP::Tool
+        tool_name 'decode_tx'
+
+        description <<~DESC.strip
+          Decode a raw BSV transaction hex string into a structured JSON object.
+
+          Accepts standard raw transaction hex (not BEEF format). Returns:
+          - txid: transaction ID in display byte order (as seen in block explorers)
+          - version: transaction version number (typically 1)
+          - lock_time: transaction locktime (0 means no locktime)
+          - inputs: array of inputs, each with:
+            - prev_txid: the txid of the output being spent
+            - vout: output index in the previous transaction
+            - script_hex: raw unlocking script as hex
+            - script_asm: unlocking script in ASM notation
+            - sequence: input sequence number
+          - outputs: array of outputs, each with:
+            - index: output index in this transaction
+            - satoshis: value in satoshis
+            - script_hex: raw locking script as hex
+            - script_asm: locking script in ASM notation
+            - script_type: detected script type (pubkeyhash, nulldata, pubkey, etc.)
+
+          Note: input prev_txids are shown in display byte order. The raw wire
+          format stores them reversed; this tool normalises them for readability.
+        DESC
+
+        input_schema(
+          type: 'object',
+          properties: {
+            hex: {
+              type: 'string',
+              description: 'Raw transaction hex string (not BEEF format).'
+            }
+          },
+          required: ['hex']
+        )
+
+        def self.call(hex:, **)
+          tx = BSV::Transaction::Transaction.from_hex(hex)
+          result = Helpers.transaction_to_h(tx)
+
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(result.to_json)],
+            structured_content: result
+          )
+        rescue ArgumentError => e
+          Helpers.error_response(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/bsv/mcp/tools/fetch_tx.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module BSV
+  module MCP
+    module Tools
+      # Fetches a transaction from the BSV network by its txid using the
+      # WhatsOnChain API, returning both the raw hex and decoded structure.
+      class FetchTx < ::MCP::Tool
+        tool_name 'fetch_tx'
+
+        description <<~DESC.strip
+          Fetch a transaction from the BSV network by its transaction ID.
+
+          Queries the WhatsOnChain API and returns the raw transaction hex
+          plus a decoded representation of its structure. Requires network access.
+
+          Parameters:
+          - txid: 64-character hex transaction ID (as shown in block explorers)
+          - network: 'mainnet' or 'testnet' — overrides the server default
+
+          Returns:
+          - txid: the transaction ID (confirmed by parsing)
+          - hex: raw transaction hex
+          - version: transaction version number
+          - lock_time: transaction locktime (0 = no locktime)
+          - inputs: array of inputs (prev_txid, vout, script_hex, script_asm, sequence)
+          - outputs: array of outputs (index, satoshis, script_hex, script_asm, script_type)
+
+          Note: WhatsOnChain returns raw transaction hex (not BEEF or EF format).
+          The txid in the response is derived by double-SHA-256 of the parsed tx,
+          and is shown in display byte order (matching block explorers).
+        DESC
+
+        input_schema(
+          type: 'object',
+          properties: {
+            txid: {
+              type: 'string',
+              description: '64-character hex transaction ID.'
+            },
+            network: {
+              type: 'string',
+              enum: %w[mainnet testnet],
+              description: 'Network to query. Overrides the server default.'
+            }
+          },
+          required: ['txid']
+        )
+
+        def self.call(txid:, network: nil, server_context: nil)
+          net_sym = Helpers.resolve_network_sym(network, server_context)
+          woc = BSV::Network::WhatsOnChain.new(network: net_sym)
+          tx = woc.fetch_transaction(txid)
+
+          result = {
+            hex: tx.to_hex,
+            network: net_sym.to_s
+          }.merge(Helpers.transaction_to_h(tx))
+
+          ::MCP::Tool::Response.new(
+            [::MCP::Content::Text.new(result.to_json)],
+            structured_content: result
+          )
+        rescue BSV::Network::ChainProviderError => e
+          Helpers.error_response("#{e.message} (HTTP #{e.status_code})")
+        rescue ArgumentError => e
+          Helpers.error_response(e.message)
+        end
+      end
+    end
+  end
+end