bitcoinkernel 0.1.0

data/lib/bitcoinkernel/txid.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  # Represents a transaction ID (txid).
+  class Txid < FFI::AutoPointer
+    # @param [FFI::Pointer] ptr Pointer to btck_Txid
+    # @param [Boolean] owned Whether this object owns the pointer.
+    #   When obtained via Transaction#txid_ptr, the pointer is NOT owned
+    #   and depends on the lifetime of the parent Transaction.
+    #   In that case, owned should be false to prevent double-free.
+    def initialize(ptr, owned: true)
+      super(ptr)
+      self.autorelease = owned
+    end
+
+    def self.release(ptr)
+      BitcoinKernel.btck_txid_destroy(ptr)
+    end
+
+    # Get the txid as raw bytes.
+    # @return [String] 32-byte binary string
+    def to_bytes
+      output = FFI::MemoryPointer.new(:uint8, 32)
+      BitcoinKernel.btck_txid_to_bytes(self, output)
+      output.read_bytes(32)
+    end
+
+    # Get the txid as hex string (little-endian, as commonly displayed).
+    # @return [String]
+    def to_hex
+      to_bytes.reverse.unpack1('H*')
+    end
+
+    # Compare two txids for equality.
+    # @param [Txid] other The other txid to compare
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Txid)
+      BitcoinKernel.btck_txid_equals(self, other) == 1
+    end
+  end
+end

data/lib/bitcoinkernel/validation_interface.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  # Base class for receiving validation interface callbacks.
+  # Subclass this and override the methods you need.
+  #
+  # @example
+  #   class MyValidationInterface < BitcoinKernel::ValidationInterface
+  #     def block_checked(block, state)
+  #       if state.valid?
+  #         puts "Block valid: #{block.block_hash.to_hex}"
+  #       end
+  #     end
+  #
+  #     def block_connected(block, entry)
+  #       puts "Block connected at height #{entry.height}"
+  #     end
+  #   end
+  #
+  #   vi = MyValidationInterface.new
+  #   options = BitcoinKernel::ContextOptions.create
+  #   options.set_validation_interface(vi)
+  class ValidationInterface
+    def initialize
+      # Store procs to prevent garbage collection
+      @stored_procs = []
+    end
+
+    # Called when a block has been fully validated.
+    # @param [Block] block The validated block
+    # @param [BlockValidationState] state The validation state
+    def block_checked(block, state)
+      # Override in subclass
+    end
+
+    # Called when a block extends the header chain with valid PoW.
+    # @param [Block] block The block
+    # @param [BlockTreeEntry] entry The block tree entry
+    def pow_valid_block(block, entry)
+      # Override in subclass
+    end
+
+    # Called when a block is connected to the best chain.
+    # @param [Block] block The connected block
+    # @param [BlockTreeEntry] entry The block tree entry
+    def block_connected(block, entry)
+      # Override in subclass
+    end
+
+    # Called when a block is disconnected during a reorg.
+    # @param [Block] block The disconnected block
+    # @param [BlockTreeEntry] entry The block tree entry
+    def block_disconnected(block, entry)
+      # Override in subclass
+    end
+
+    # Build the FFI callbacks struct.
+    # @return [ValidationInterfaceCallbacks]
+    # @api private
+    def to_ffi_callbacks
+      callbacks = ValidationInterfaceCallbacks.new
+
+      callbacks[:user_data] = FFI::Pointer::NULL
+      callbacks[:user_data_destroy] = nil
+
+      block_checked_proc = create_block_checked_proc
+      @stored_procs << block_checked_proc
+      callbacks[:block_checked] = block_checked_proc
+
+      pow_valid_block_proc = create_block_entry_proc(:pow_valid_block)
+      @stored_procs << pow_valid_block_proc
+      callbacks[:pow_valid_block] = pow_valid_block_proc
+
+      block_connected_proc = create_block_entry_proc(:block_connected)
+      @stored_procs << block_connected_proc
+      callbacks[:block_connected] = block_connected_proc
+
+      block_disconnected_proc = create_block_entry_proc(:block_disconnected)
+      @stored_procs << block_disconnected_proc
+      callbacks[:block_disconnected] = block_disconnected_proc
+
+      callbacks
+    end
+
+    private
+
+    def create_block_checked_proc
+      proc do |_user_data, block_ptr, state_ptr|
+        # Copy the block since the pointer may not be owned
+        copied_ptr = BitcoinKernel.btck_block_copy(block_ptr)
+        block = Block.new(copied_ptr)
+        state = BlockValidationState.new(state_ptr)
+        block_checked(block, state)
+      end
+    end
+
+    def create_block_entry_proc(method_name)
+      proc do |_user_data, block_ptr, entry_ptr|
+        # Copy the block since the pointer may not be owned
+        copied_ptr = BitcoinKernel.btck_block_copy(block_ptr)
+        block = Block.new(copied_ptr)
+        entry = BlockTreeEntry.new(entry_ptr, owned: false)
+        send(method_name, block, entry)
+      end
+    end
+  end
+end

data/lib/bitcoinkernel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  VERSION = "0.1.0"
+end

data/lib/bitcoinkernel.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative "bitcoinkernel/version"
+require 'ffi'
+
+# Bitcoin Kernel bindings.
+module BitcoinKernel
+  class Error < StandardError; end
+
+  extend FFI::Library
+  ffi_lib(ENV['LIB_BITCOINKERNEL_PATH'])
+
+  # Chain types
+  module ChainType
+    MAINNET = 0
+    TESTNET = 1
+    TESTNET_4 = 2
+    SIGNET = 3
+    REGTEST = 4
+  end
+
+  # Validation modes
+  module ValidationMode
+    VALID = 0
+    INVALID = 1
+    INTERNAL_ERROR = 2
+  end
+
+  # Block validation results
+  module BlockValidationResult
+    UNSET = 0
+    CONSENSUS = 1
+    CACHED_INVALID = 2
+    INVALID_HEADER = 3
+    MUTATED = 4
+    MISSING_PREV = 5
+    INVALID_PREV = 6
+    TIME_FUTURE = 7
+    HEADER_LOW_WORK = 8
+  end
+
+  # Script verification flags
+  module ScriptFlags
+    NONE = 0
+    P2SH = (1 << 0)
+    DERSIG = (1 << 2)
+    NULLDUMMY = (1 << 4)
+    CHECKLOCKTIMEVERIFY = (1 << 9)
+    CHECKSEQUENCEVERIFY = (1 << 10)
+    WITNESS = (1 << 11)
+    TAPROOT = (1 << 17)
+    ALL = P2SH | DERSIG | NULLDUMMY | CHECKLOCKTIMEVERIFY | CHECKSEQUENCEVERIFY | WITNESS | TAPROOT
+  end
+
+  # Load Logging module early (required for attach_function)
+  require_relative 'bitcoinkernel/logging'
+
+  # Callback for serializing data
+  callback :btck_write_bytes, [:pointer, :size_t, :pointer], :int
+
+  # Validation interface callbacks
+  callback :btck_validation_interface_block_checked, [:pointer, :pointer, :pointer], :void
+  callback :btck_validation_interface_pow_valid_block, [:pointer, :pointer, :pointer], :void
+  callback :btck_validation_interface_block_connected, [:pointer, :pointer, :pointer], :void
+  callback :btck_validation_interface_block_disconnected, [:pointer, :pointer, :pointer], :void
+  callback :btck_destroy_callback, [:pointer], :void
+
+  # Validation interface callbacks struct
+  class ValidationInterfaceCallbacks < FFI::Struct
+    layout :user_data, :pointer,
+           :user_data_destroy, :btck_destroy_callback,
+           :block_checked, :btck_validation_interface_block_checked,
+           :pow_valid_block, :btck_validation_interface_pow_valid_block,
+           :block_connected, :btck_validation_interface_block_connected,
+           :block_disconnected, :btck_validation_interface_block_disconnected
+  end
+
+  # Logging
+  attach_function :btck_logging_disable, [], :void
+  attach_function :btck_logging_set_options, [Logging::Options.by_value], :void
+  attach_function :btck_logging_set_level_category, [:uint8, :uint8], :void
+  attach_function :btck_logging_enable_category, [:uint8], :void
+  attach_function :btck_logging_disable_category, [:uint8], :void
+
+  # Chain parameters
+  attach_function :btck_chain_parameters_create, [:uint8], :pointer
+  attach_function :btck_chain_parameters_destroy, [:pointer], :void
+
+  # Context options
+  attach_function :btck_context_options_create, [], :pointer
+  attach_function :btck_context_options_set_chainparams, [:pointer, :pointer], :void
+  attach_function :btck_context_options_set_validation_interface, [:pointer, ValidationInterfaceCallbacks.by_value], :void
+  attach_function :btck_context_options_destroy, [:pointer], :void
+
+  # Context
+  attach_function :btck_context_create, [:pointer], :pointer
+  attach_function :btck_context_destroy, [:pointer], :void
+  attach_function :btck_context_interrupt, [:pointer], :int
+
+  # Chainstate manager options
+  attach_function :btck_chainstate_manager_options_create, [:pointer, :string, :size_t, :string, :size_t], :pointer
+  attach_function :btck_chainstate_manager_options_set_worker_threads_num, [:pointer, :int], :void
+  attach_function :btck_chainstate_manager_options_set_wipe_dbs, [:pointer, :int, :int], :int
+  attach_function :btck_chainstate_manager_options_update_block_tree_db_in_memory, [:pointer, :int], :void
+  attach_function :btck_chainstate_manager_options_update_chainstate_db_in_memory, [:pointer, :int], :void
+  attach_function :btck_chainstate_manager_options_destroy, [:pointer], :void
+
+  # Chainstate manager
+  attach_function :btck_chainstate_manager_create, [:pointer], :pointer
+  attach_function :btck_chainstate_manager_process_block, [:pointer, :pointer, :pointer], :int
+  attach_function :btck_chainstate_manager_get_active_chain, [:pointer], :pointer
+  attach_function :btck_chainstate_manager_get_block_tree_entry_by_hash, [:pointer, :pointer], :pointer
+  attach_function :btck_chainstate_manager_destroy, [:pointer], :void
+
+  # Block
+  attach_function :btck_block_create, [:pointer, :size_t], :pointer
+  attach_function :btck_block_copy, [:pointer], :pointer
+  attach_function :btck_block_count_transactions, [:pointer], :size_t
+  attach_function :btck_block_get_transaction_at, [:pointer, :size_t], :pointer
+  attach_function :btck_block_get_hash, [:pointer], :pointer
+  attach_function :btck_block_to_bytes, [:pointer, :btck_write_bytes, :pointer], :int
+  attach_function :btck_block_destroy, [:pointer], :void
+
+  # Block hash
+  attach_function :btck_block_hash_create, [:pointer], :pointer
+  attach_function :btck_block_hash_equals, [:pointer, :pointer], :int
+  attach_function :btck_block_hash_to_bytes, [:pointer, :pointer], :void
+  attach_function :btck_block_hash_destroy, [:pointer], :void
+
+  # Block validation state
+  attach_function :btck_block_validation_state_get_validation_mode, [:pointer], :uint8
+  attach_function :btck_block_validation_state_get_block_validation_result, [:pointer], :uint32
+
+  # Chain
+  attach_function :btck_chain_get_height, [:pointer], :int32
+  attach_function :btck_chain_get_by_height, [:pointer, :int], :pointer
+  attach_function :btck_chain_contains, [:pointer, :pointer], :int
+
+  # Block tree entry
+  attach_function :btck_block_tree_entry_get_height, [:pointer], :int32
+  attach_function :btck_block_tree_entry_get_block_hash, [:pointer], :pointer
+  attach_function :btck_block_tree_entry_get_previous, [:pointer], :pointer
+  attach_function :btck_block_tree_entry_equals, [:pointer, :pointer], :int
+
+  # Block read (requires ChainstateManager)
+  attach_function :btck_block_read, [:pointer, :pointer], :pointer
+
+  # Transaction
+  attach_function :btck_transaction_create, [:pointer, :size_t], :pointer
+  attach_function :btck_transaction_copy, [:pointer], :pointer
+  attach_function :btck_transaction_to_bytes, [:pointer, :btck_write_bytes, :pointer], :int
+  attach_function :btck_transaction_count_outputs, [:pointer], :size_t
+  attach_function :btck_transaction_count_inputs, [:pointer], :size_t
+  attach_function :btck_transaction_get_output_at, [:pointer, :size_t], :pointer
+  attach_function :btck_transaction_get_input_at, [:pointer, :size_t], :pointer
+  attach_function :btck_transaction_get_txid, [:pointer], :pointer
+  attach_function :btck_transaction_destroy, [:pointer], :void
+
+  # Transaction output
+  attach_function :btck_transaction_output_create, [:pointer, :int64], :pointer
+  attach_function :btck_transaction_output_get_script_pubkey, [:pointer], :pointer
+  attach_function :btck_transaction_output_get_amount, [:pointer], :int64
+  attach_function :btck_transaction_output_destroy, [:pointer], :void
+
+  # Script pubkey
+  attach_function :btck_script_pubkey_create, [:pointer, :size_t], :pointer
+  attach_function :btck_script_pubkey_verify, [:pointer, :int64, :pointer, :pointer, :uint, :uint32, :pointer], :int
+  attach_function :btck_script_pubkey_to_bytes, [:pointer, :btck_write_bytes, :pointer], :int
+  attach_function :btck_script_pubkey_destroy, [:pointer], :void
+
+  # Precomputed transaction data
+  attach_function :btck_precomputed_transaction_data_create, [:pointer, :pointer, :size_t], :pointer
+  attach_function :btck_precomputed_transaction_data_destroy, [:pointer], :void
+
+  # Txid
+  attach_function :btck_txid_equals, [:pointer, :pointer], :int
+  attach_function :btck_txid_to_bytes, [:pointer, :pointer], :void
+  attach_function :btck_txid_destroy, [:pointer], :void
+
+  # Transaction input
+  attach_function :btck_transaction_input_get_out_point, [:pointer], :pointer
+  attach_function :btck_transaction_input_destroy, [:pointer], :void
+
+  # Transaction out point
+  attach_function :btck_transaction_out_point_get_index, [:pointer], :uint32
+  attach_function :btck_transaction_out_point_get_txid, [:pointer], :pointer
+  attach_function :btck_transaction_out_point_destroy, [:pointer], :void
+
+  autoload :Serializable, 'bitcoinkernel/serializable'
+  autoload :Block, 'bitcoinkernel/block'
+  autoload :BlockHash, 'bitcoinkernel/block_hash'
+  autoload :Transaction, 'bitcoinkernel/transaction'
+  autoload :TransactionInput, 'bitcoinkernel/transaction_input'
+  autoload :TransactionOutPoint, 'bitcoinkernel/transaction_out_point'
+  autoload :TransactionOutput, 'bitcoinkernel/transaction_output'
+  autoload :ScriptPubkey, 'bitcoinkernel/script_pubkey'
+  autoload :Txid, 'bitcoinkernel/txid'
+  autoload :ChainParameters, 'bitcoinkernel/chain_parameters'
+  autoload :ContextOptions, 'bitcoinkernel/context_options'
+  autoload :Context, 'bitcoinkernel/context'
+  autoload :ChainstateManagerOptions, 'bitcoinkernel/chainstate_manager_options'
+  autoload :ChainstateManager, 'bitcoinkernel/chainstate_manager'
+  autoload :Chain, 'bitcoinkernel/chain'
+  autoload :BlockTreeEntry, 'bitcoinkernel/block_tree_entry'
+  autoload :BlockValidationState, 'bitcoinkernel/block_validation_state'
+  autoload :ValidationInterface, 'bitcoinkernel/validation_interface'
+end

data/sig/bitcoinkernel.rbs

@@ -0,0 +1,4 @@
+module Bitcoinkernel
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: bitcoinkernel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- azuchi
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.17.2
+description: Ruby bindings for BitcoinKernel.
+email:
+- azuchi@chaintope.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".ruby-gemset"
+- ".ruby-version"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/bitcoinkernel.rb
+- lib/bitcoinkernel/block.rb
+- lib/bitcoinkernel/block_hash.rb
+- lib/bitcoinkernel/block_tree_entry.rb
+- lib/bitcoinkernel/block_validation_state.rb
+- lib/bitcoinkernel/chain.rb
+- lib/bitcoinkernel/chain_parameters.rb
+- lib/bitcoinkernel/chainstate_manager.rb
+- lib/bitcoinkernel/chainstate_manager_options.rb
+- lib/bitcoinkernel/context.rb
+- lib/bitcoinkernel/context_options.rb
+- lib/bitcoinkernel/logging.rb
+- lib/bitcoinkernel/script_pubkey.rb
+- lib/bitcoinkernel/serializable.rb
+- lib/bitcoinkernel/transaction.rb
+- lib/bitcoinkernel/transaction_input.rb
+- lib/bitcoinkernel/transaction_out_point.rb
+- lib/bitcoinkernel/transaction_output.rb
+- lib/bitcoinkernel/txid.rb
+- lib/bitcoinkernel/validation_interface.rb
+- lib/bitcoinkernel/version.rb
+- sig/bitcoinkernel.rbs
+homepage: https://github.com/azuchi/bitcoinkernelrb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/azuchi/bitcoinkernelrb
+  source_code_uri: https://github.com/azuchi/bitcoinkernelrb
+  changelog_uri: https://github.com/azuchi/bitcoinkernelrb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby bindings for BitcoinKernel.
+test_files: []