bitcoinkernel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81fd6124378d97dca07b53f429d67010f042c40c75ddc6be286bb5435b1a367f
+  data.tar.gz: f20221f63791bf6f6b8489243bb7b30c3e89325c78527d1bfa17a317c9822be6
+SHA512:
+  metadata.gz: 55e486721451529db4469257c9b204608d611b095b04390150a575f29e49bf9dab320b9c919f2b3898e4a5cc51b860ea3f356b158e6dc5c9bf233cef694ecb1c
+  data.tar.gz: cb72d62d2d6f8f55af9cb83c03406a7cdd27e28986abec5e35e14ee3163560674c09ee48386f43de1033c9e0733f270b6f9e5b31d09309b038b8ab5a1f5091ea

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-gemset

@@ -0,0 +1 @@
+bitcoinkernel

data/.ruby-version

@@ -0,0 +1 @@
+ruby-4.0.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 azuchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,232 @@
+# BitcoinKernel
+
+Ruby bindings for [libbitcoinkernel](https://github.com/bitcoin/bitcoin/blob/master/doc/design/libraries.md#libbitcoinkernel), the Bitcoin Core consensus engine library.
+
+## Requirements
+
+- Ruby 3.0+
+- libbitcoinkernel shared library
+
+You need to build libbitcoinkernel from Bitcoin Core source:
+
+```bash
+git clone https://github.com/bitcoin/bitcoin.git
+cd bitcoin
+cmake -B build -DBUILD_KERNEL_LIB=ON -DBUILD_SHARED_LIBS=ON
+cmake --build build
+```
+
+Set the `LIB_BITCOINKERNEL_PATH` environment variable to point to the built library:
+
+```bash
+export LIB_BITCOINKERNEL_PATH=/path/to/bitcoin/build/src/kernel/libbitcoinkernel.so
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'bitcoinkernel'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install bitcoinkernel
+```
+
+## Usage
+
+### Basic Block Parsing
+
+```ruby
+require 'bitcoinkernel'
+
+# Parse a block from raw bytes
+block_hex = "0100000000000000..."
+block = BitcoinKernel::Block.from_raw([block_hex].pack('H*'))
+
+# Access block properties
+puts block.block_hash.to_hex
+puts "Transaction count: #{block.transaction_count}"
+
+# Iterate transactions
+block.transactions.each do |tx|
+  puts "Txid: #{tx.txid.to_hex}"
+  puts "Inputs: #{tx.input_count}, Outputs: #{tx.output_count}"
+end
+
+# Serialize back to bytes
+raw_bytes = block.to_bytes
+```
+
+### Transaction Parsing
+
+```ruby
+# Parse a transaction
+tx = BitcoinKernel::Transaction.from_raw(raw_tx_bytes)
+
+# Access inputs
+tx.inputs.each do |input|
+  out_point = input.out_point
+  puts "Spending #{out_point.txid.to_hex}:#{out_point.index}"
+end
+
+# Access outputs
+tx.outputs.each_with_index do |output, i|
+  puts "Output #{i}: #{output.amount} satoshis"
+end
+```
+
+### Script Verification
+
+```ruby
+# Verify a script
+script = BitcoinKernel::ScriptPubkey.from_raw(script_bytes)
+
+result = script.verify(
+  amount: 50_0000_0000,  # in satoshis
+  tx: spending_tx,
+  input_index: 0,
+  flags: BitcoinKernel::ScriptFlags::ALL
+)
+
+puts result ? "Valid" : "Invalid"
+```
+
+### Chainstate Management
+
+```ruby
+# Disable logging (optional)
+BitcoinKernel::Logging.disable
+
+# Create context with chain parameters
+options = BitcoinKernel::ContextOptions.create
+params = BitcoinKernel::ChainParameters.regtest  # or .mainnet, .testnet, etc.
+options.set_chainparams(params)
+context = BitcoinKernel::Context.create(options)
+
+# Create chainstate manager
+cs_options = BitcoinKernel::ChainstateManagerOptions.create(
+  context: context,
+  data_directory: "/path/to/data",
+  blocks_directory: "/path/to/blocks"
+)
+cs_options.set_block_tree_db_in_memory
+cs_options.set_chainstate_db_in_memory
+
+manager = BitcoinKernel::ChainstateManager.create(cs_options)
+
+# Process blocks
+block = BitcoinKernel::Block.from_raw(block_bytes)
+manager.process_block(block)
+
+# Query the chain
+chain = manager.active_chain
+puts "Chain height: #{chain.height}"
+
+entry = chain.entry_at(0)
+puts "Genesis hash: #{entry.block_hash.to_hex}"
+```
+
+### Validation Interface
+
+```ruby
+# Create a custom validation interface
+class MyValidationInterface < BitcoinKernel::ValidationInterface
+  def block_checked(block, state)
+    if state.valid?
+      puts "Block valid: #{block.block_hash.to_hex}"
+    else
+      puts "Block invalid"
+    end
+  end
+
+  def block_connected(block, entry)
+    puts "Block connected at height #{entry.height}"
+  end
+end
+
+# Use with context
+vi = MyValidationInterface.new
+options = BitcoinKernel::ContextOptions.create
+options.set_validation_interface(vi)
+context = BitcoinKernel::Context.create(options)
+```
+
+### Logging Configuration
+
+```ruby
+# Disable all logging
+BitcoinKernel::Logging.disable
+
+# Or configure logging options
+BitcoinKernel::Logging.set_options(
+  timestamps: true,
+  time_micros: false,
+  threadnames: false,
+  sourcelocations: false,
+  category_levels: true
+)
+
+# Set log level for specific category
+BitcoinKernel::Logging.set_level(
+  BitcoinKernel::Logging::Category::VALIDATION,
+  BitcoinKernel::Logging::Level::DEBUG
+)
+
+# Enable/disable categories
+BitcoinKernel::Logging.enable_category(BitcoinKernel::Logging::Category::ALL)
+BitcoinKernel::Logging.disable_category(BitcoinKernel::Logging::Category::MEMPOOL)
+```
+
+## API Reference
+
+### Core Classes
+
+| Class | Description |
+|-------|-------------|
+| `Block` | Bitcoin block with header and transactions |
+| `BlockHash` | 32-byte block hash |
+| `Transaction` | Bitcoin transaction |
+| `Txid` | 32-byte transaction ID |
+| `TransactionInput` | Transaction input |
+| `TransactionOutput` | Transaction output with amount and script |
+| `TransactionOutPoint` | Reference to a previous output (txid + index) |
+| `ScriptPubkey` | Output script with verification support |
+
+### Chain Management
+
+| Class | Description |
+|-------|-------------|
+| `Context` | Kernel context for chain operations |
+| `ContextOptions` | Configuration for context creation |
+| `ChainParameters` | Network parameters (mainnet, testnet, regtest, etc.) |
+| `ChainstateManager` | Manages blockchain state and validation |
+| `ChainstateManagerOptions` | Configuration for chainstate manager |
+| `Chain` | Active blockchain view |
+| `BlockTreeEntry` | Entry in the block tree |
+| `BlockValidationState` | Validation result for a block |
+| `ValidationInterface` | Callbacks for validation events |
+
+### Constants
+
+| Module | Description |
+|--------|-------------|
+| `ChainType` | Network types (MAINNET, TESTNET, REGTEST, etc.) |
+| `ScriptFlags` | Script verification flags |
+| `ValidationMode` | Block validation modes |
+| `BlockValidationResult` | Validation failure reasons |
+| `Logging::Category` | Log categories |
+| `Logging::Level` | Log levels (TRACE, DEBUG, INFO) |
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/bitcoinkernel/block.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  # Represents a Bitcoin block.
+  class Block < FFI::AutoPointer
+    include Serializable
+    serialize_with :btck_block_to_bytes
+
+    # Create a Block from raw serialized data.
+    # @param [String] raw_block Serialized block data (binary string)
+    # @return [Block]
+    def self.from_raw(raw_block)
+      raw_ptr = FFI::MemoryPointer.new(:uint8, raw_block.bytesize)
+      raw_ptr.put_bytes(0, raw_block)
+      ptr = BitcoinKernel.btck_block_create(raw_ptr, raw_block.bytesize)
+      raise Error, "Failed to create block from raw data" if ptr.null?
+      new(ptr)
+    end
+
+    def self.release(ptr)
+      BitcoinKernel.btck_block_destroy(ptr)
+    end
+
+    # Create a copy of this block.
+    # @return [Block] A new Block instance with copied data
+    def copy
+      copied_ptr = BitcoinKernel.btck_block_copy(self)
+      raise Error, "Failed to copy block" if copied_ptr.null?
+      Block.new(copied_ptr)
+    end
+
+    # Compare two blocks for equality by their block hash.
+    # @param [Block] other The other block to compare
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Block)
+      block_hash == other.block_hash
+    end
+
+    # Number of transactions in the block.
+    # @return [Integer]
+    def transaction_count
+      BitcoinKernel.btck_block_count_transactions(self)
+    end
+
+    # Get transaction at specified index.
+    # @param [Integer] index Transaction index
+    # @return [Transaction]
+    def transaction_at(index)
+      tx_ptr = BitcoinKernel.btck_block_get_transaction_at(self, index)
+      raise Error, "Transaction not found at index #{index}" if tx_ptr.null?
+      # Copy the transaction since the returned pointer is not owned
+      copied_ptr = BitcoinKernel.btck_transaction_copy(tx_ptr)
+      Transaction.new(copied_ptr)
+    end
+
+    # Get all transactions in the block.
+    # @return [Array<Transaction>]
+    def transactions
+      transaction_count.times.map { |i| transaction_at(i) }
+    end
+
+    # Get the block hash.
+    # @return [BlockHash]
+    def block_hash
+      hash_ptr = BitcoinKernel.btck_block_get_hash(self)
+      raise Error, "Failed to get block hash" if hash_ptr.null?
+      BlockHash.new(hash_ptr)
+    end
+  end
+end

data/lib/bitcoinkernel/block_hash.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  # Represents a block hash.
+  class BlockHash < FFI::AutoPointer
+    # Create a BlockHash from raw bytes.
+    # @param [String] bytes 32-byte hash (binary string)
+    # @return [BlockHash]
+    def self.from_bytes(bytes)
+      raise Error, "Block hash must be 32 bytes" unless bytes.bytesize == 32
+      raw_ptr = FFI::MemoryPointer.new(:uint8, 32)
+      raw_ptr.put_bytes(0, bytes)
+      ptr = BitcoinKernel.btck_block_hash_create(raw_ptr)
+      raise Error, "Failed to create block hash" if ptr.null?
+      new(ptr)
+    end
+
+    # Create a BlockHash from hex string.
+    # @param [String] hex 64-character hex string (little-endian, as commonly displayed)
+    # @return [BlockHash]
+    def self.from_hex(hex)
+      bytes = [hex].pack('H*').reverse
+      from_bytes(bytes)
+    end
+
+    def self.release(ptr)
+      BitcoinKernel.btck_block_hash_destroy(ptr)
+    end
+
+    # Get the hash as raw bytes.
+    # @return [String] 32-byte binary string
+    def to_bytes
+      output = FFI::MemoryPointer.new(:uint8, 32)
+      BitcoinKernel.btck_block_hash_to_bytes(self, output)
+      output.read_bytes(32)
+    end
+
+    # Get the hash as hex string (little-endian, as commonly displayed).
+    # @return [String]
+    def to_hex
+      to_bytes.reverse.unpack1('H*')
+    end
+
+    # Compare two block hashes for equality.
+    # @param [BlockHash] other The other block hash to compare
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(BlockHash)
+      BitcoinKernel.btck_block_hash_equals(self, other) == 1
+    end
+  end
+end

data/lib/bitcoinkernel/block_tree_entry.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  # Represents an entry in the block tree.
+  #
+  # Note: This class does not inherit from FFI::AutoPointer because:
+  # - There is no btck_block_tree_entry_destroy function in the library
+  # - The pointer is not owned; it points to internal data of ChainstateManager
+  # - The lifetime depends on the parent ChainstateManager or Chain
+  class BlockTreeEntry
+    # @param [FFI::Pointer] ptr Pointer to btck_BlockTreeEntry
+    # @param [Boolean] owned Whether this object owns the pointer.
+    #   BlockTreeEntry pointers from Chain/ChainstateManager are NOT owned.
+    def initialize(ptr, owned: false)
+      @ptr = ptr
+      @owned = owned
+    end
+
+    # Get the height of this block in the chain.
+    # @return [Integer]
+    def height
+      BitcoinKernel.btck_block_tree_entry_get_height(@ptr)
+    end
+
+    # Get the block hash.
+    # @return [BlockHash]
+    def block_hash
+      ptr = BitcoinKernel.btck_block_tree_entry_get_block_hash(@ptr)
+      raise Error, "Failed to get block hash" if ptr.null?
+      # The returned pointer is not owned, but we need to copy it for safety
+      bytes = FFI::MemoryPointer.new(:uint8, 32)
+      BitcoinKernel.btck_block_hash_to_bytes(ptr, bytes)
+      BlockHash.from_bytes(bytes.read_bytes(32))
+    end
+
+    # Get the previous block tree entry.
+    # @return [BlockTreeEntry, nil] The previous entry, or nil if this is the genesis block
+    def previous
+      ptr = BitcoinKernel.btck_block_tree_entry_get_previous(@ptr)
+      return nil if ptr.null?
+      BlockTreeEntry.new(ptr, owned: false)
+    end
+
+    # Compare two block tree entries for equality.
+    # @param [BlockTreeEntry] other The other entry to compare
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(BlockTreeEntry)
+      BitcoinKernel.btck_block_tree_entry_equals(@ptr, other.to_ptr) == 1
+    end
+
+    # Get the underlying pointer for FFI calls.
+    # @return [FFI::Pointer]
+    def to_ptr
+      @ptr
+    end
+  end
+end

data/lib/bitcoinkernel/block_validation_state.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module BitcoinKernel
+  # Represents the validation state of a block.
+  #
+  # Note: This class does not inherit from FFI::AutoPointer because:
+  # - There is no btck_block_validation_state_destroy function in the library
+  # - The pointer is not owned; it is passed to ValidationInterface callbacks
+  # - The lifetime is only valid during the callback execution
+  #
+  # This object is obtained through the ValidationInterface#block_checked callback.
+  class BlockValidationState
+    # @param [FFI::Pointer] ptr Pointer to btck_BlockValidationState
+    def initialize(ptr)
+      @ptr = ptr
+    end
+
+    # Get the validation mode.
+    # @return [Integer] One of ValidationMode constants (VALID, INVALID, INTERNAL_ERROR)
+    def validation_mode
+      BitcoinKernel.btck_block_validation_state_get_validation_mode(@ptr)
+    end
+
+    # Check if the block is valid.
+    # @return [Boolean]
+    def valid?
+      validation_mode == ValidationMode::VALID
+    end
+
+    # Check if the block is invalid.
+    # @return [Boolean]
+    def invalid?
+      validation_mode == ValidationMode::INVALID
+    end
+
+    # Check if there was an internal error during validation.
+    # @return [Boolean]
+    def internal_error?
+      validation_mode == ValidationMode::INTERNAL_ERROR
+    end
+
+    # Get the block validation result (reason for invalidity).
+    # @return [Integer] One of BlockValidationResult constants
+    def block_validation_result
+      BitcoinKernel.btck_block_validation_state_get_block_validation_result(@ptr)
+    end
+
+    # Get the underlying pointer for FFI calls.
+    # @return [FFI::Pointer]
+    def to_ptr
+      @ptr
+    end
+  end
+end