Ruby Blockchain Example

Educational implementation of core blockchain primitives in Ruby: blocks, transactions, proof-of-work difficulty, chain validation, and service objects.

Features

• Create the genesis block and initialize the chain via Case::Blockchain::Create and Case::Block::CreateGenesis.
• Add new blocks with transaction data through Case::Blockchain::Add.
• Validate chain integrity and difficulty with Case::Blockchain::Validate.
• Typed entities and value objects on dry-struct/dry-types with Zeitwerk autoloading.

Tech stack

• Ruby 3.4.7
• dry-rb (dry-struct, dry-types, dry-initializer)
• resol (service layer)
• zeitwerk (autoload)
• rspec, simplecov/simplecov-lcov, rubocop, pry

Project structure

app/
case/ # service objects
entity/ # block, transaction, blockchain entities
value/ # transaction input/output value objects
config.rb # dependencies and Zeitwerk setup
spec/ # RSpec tests

Getting started

1. Install Ruby 3.4.7 (rbenv/rvm) and Bundler.
2. Install dependencies:

   bundle install

3. Run tests:

   bundle exec rspec

Usage examples

Create a chain, add a block, and validate:

require_relative"config"input=Value::Transaction::Input.new(transaction_id: "0" * 64,output_index: 0)output=Value::Transaction::Output.new(address: "demo_wallet",amount: BigDecimal("1.0"))transaction=Entity::Transaction.build([input],[output])blockchain=Case::Blockchain::Create.call!Case::Blockchain::Add.call!(blockchain,[transaction])valid=Case::Blockchain::Validate.call!(blockchain)puts"Chain valid? #{valid}"

Create a chain with custom difficulty and multiple transactions:

require_relative"config"input1=Value::Transaction::Input.new(transaction_id: "a" * 64,output_index: 0)output1=Value::Transaction::Output.new(address: "alice",amount: BigDecimal("0.5"))input2=Value::Transaction::Input.new(transaction_id: "b" * 64,output_index: 1)output2=Value::Transaction::Output.new(address: "bob",amount: BigDecimal("0.25"))transactions=[Entity::Transaction.build([input1],[output1]),Entity::Transaction.build([input2],[output2]),]blockchain=Case::Blockchain::Create.call!(difficulty: 2)Case::Blockchain::Add.call!(blockchain,transactions)puts"Blocks in chain: #{blockchain.blocks.size}"

Commands

• Run tests: bundle exec rspec
• Coverage report (HTML and LCOV): COVER=1 bundle exec rspec (outputs to coverage/)
• Lint: bundle exec rubocop

Configuration

• Default mining difficulty is set in SimpleBlockchain.default_difficulty (see config.rb).
• SimpleCov is enabled when COVER=1 or COVER=true is set in the environment.