mini-wallet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5363b3d1d2d3dd287d1ab89d3e8ac183fca8280570498f599ff78baede7b8aa5
+  data.tar.gz: 8b4e707db9b3448700536cb60d02ebfca86eee76ad4aa716fe0c0283958c6ca2
+SHA512:
+  metadata.gz: 1e0880a384d54de15753097b62d3a7929a297c3e66082615fac1345621c96974e0312073b16c2225e9a655c075bdebae62b00df82a6686920503522a4724fe4c
+  data.tar.gz: bd02c9181483b9f46ea7cada3bc4c036792a43508a383a39712ae4b26b1d05319c5f46eaf036e2fbcfb472a3486cfb7c2d26a14e3c083be6f3016451edf850ad

data/README.md

@@ -0,0 +1,127 @@
+
+# Минималистичный Bitcoin-кошелёк (Signet)
+
+---
+
+## Общее описание
+
+- Генерация и сохранение приватного ключа в `.wallet/signet_private_key`
+- Показ баланса на адресе
+- Отправка BTC на адрес Signet
+- Динамические комиссии за транзакции
+
+---
+
+## Запуск
+
+### 1. Сборка
+
+**Docker:**
+
+```bash
+docker compose build
+```
+
+**Makefile:**
+
+```bash
+make build
+```
+
+---
+
+### 2. Инициализация кошелька
+
+**Docker:**
+
+```bash
+docker compose run --rm mini_wallet init
+```
+
+**Makefile:**
+
+```bash
+make init
+```
+
+> Выведет адрес, на который можно получaть Signet-BTC.
+
+При тестировании кошелька тестовые суммы запрашивались с адреса:
+
+- [https://signetfaucet.bublina.eu.org/](https://signetfaucet.bublina.eu.org/)
+
+---
+
+### 3. Проверка баланса
+
+**Docker:**
+
+```bash
+docker compose run --rm mini_wallet balance
+```
+
+**Makefile:**
+
+```bash
+make balance
+```
+
+---
+
+### 4. Отправка средств
+
+**Docker:**
+
+```bash
+docker compose run --rm mini_wallet send <адрес> <сумма_в_BTC>
+```
+
+**Makefile:**
+
+```bash
+make send TO=<адрес> AMOUNT=<сумма>
+```
+
+Пример:
+
+```bash
+make send TO=tb1q... AMOUNT=0.00002
+```
+
+---
+
+## Тестирование
+
+### RSpec
+
+**Docker:**
+
+```bash
+docker compose run --rm --entrypoint rspec mini_wallet
+```
+
+**Makefile:**
+
+```bash
+make test
+```
+
+### Проверка команд с помощью bash-скрипта (опционально)
+
+Данный пункт требует наличия баланса на адресе созданного (командoй `make init`) кошелька.
+
+Перед началом выполните команду:
+
+```bash
+cp .env.example .env
+```
+
+Далее укажите в файле `.env` значение вашего текущего адреса кошелька в переменной `SENDER_ADDR`.
+Узнать адрес своего кошелька можно командой `make balance`.
+Также нужно указать signet-адрес куда будут отправляться средства - `RECIPIENT_ADDR`.
+
+После можно запустить скрипт проверки работоспособности команд кошелька.
+
+```bash
+make
+```

data/bin/mini_wallet

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require 'dry/cli'
+require 'zeitwerk'
+require 'bitcoin'
+require 'colorize'
+require 'whirly'
+
+loader = Zeitwerk::Loader.new
+loader.push_dir(File.expand_path('../lib', __dir__))
+loader.setup
+
+Dry::CLI.new(MiniWallet::Cli).call

data/lib/blockstream/client.rb

@@ -0,0 +1,42 @@
+require 'faraday'
+
+module Blockstream
+  class Client
+    BASE_URL = 'https://blockstream.info/signet/api/'.freeze
+
+    def fetch_address_info(address)
+      response = conn.get("address/#{address}")
+      handle_response(response) { |body| JSON.parse(body) }
+    end
+
+    def fetch_transaction_hex(txid)
+      response = conn.get("tx/#{txid}/hex")
+      handle_response(response) { |body| body }
+    end
+
+    def fetch_utxos(address)
+      response = conn.get("address/#{address}/utxo")
+      handle_response(response) { |body| JSON.parse(body) }
+    end
+
+    def fetch_fee_rate
+      response = conn.get('fee-estimates')
+      body = handle_response(response) { |body| JSON.parse(body) }
+      rate = body['1']
+
+      [rate.to_i, 1].max
+    end
+
+    private
+
+    def conn
+      @conn ||= Faraday.new(url: BASE_URL)
+    end
+
+    def handle_response(response)
+      raise "HTTP error #{response.status}: #{response.body}" unless response.success?
+
+      yield(response.body)
+    end
+  end
+end

data/lib/mempool/client.rb

@@ -0,0 +1,22 @@
+require 'faraday'
+
+module Mempool
+  class Client
+    BASE_URL = 'https://mempool.space/signet/api/'.freeze
+
+    def broadcast_transaction(tx_hex)
+      response = conn.post('tx') do |req|
+        req.headers['Content-Type'] = 'text/plain'
+        req.body = tx_hex
+      end
+
+      response.body
+    end
+
+    private
+
+    def conn
+      @conn ||= Faraday.new(url: BASE_URL)
+    end
+  end
+end

data/lib/mini_wallet/balance/fetch.rb

@@ -0,0 +1,25 @@
+require 'dry/initializer'
+require 'bigdecimal'
+
+module MiniWallet
+  module Balance
+    class Fetch
+      extend Dry::Initializer
+
+      option :client
+      option :address
+
+      def call
+        response = client.fetch_address_info(address)
+
+        funded = response.dig('chain_stats', 'funded_txo_sum') || 0
+        spent = response.dig('chain_stats', 'spent_txo_sum') || 0
+
+        (BigDecimal(funded - spent) / 100_000_000).to_f
+      rescue Faraday::Error, JSON::ParserError => e
+        puts "Error fetching balance: #{e.message}"
+        0.0
+      end
+    end
+  end
+end

data/lib/mini_wallet/cli.rb

@@ -0,0 +1,9 @@
+module MiniWallet
+  module Cli
+    extend Dry::CLI::Registry
+
+    register 'init', Commands::Init
+    register 'balance', Commands::Balance
+    register 'send', Commands::Send
+  end
+end

data/lib/mini_wallet/commands/balance.rb

@@ -0,0 +1,20 @@
+module MiniWallet
+  module Commands
+    class Balance < Base
+      desc 'Show BTC balance for wallet'
+
+      def call(*)
+        key = ensure_wallet_exists
+        address = key.to_p2wpkh
+
+        with_spinner do
+          client = Blockstream::Client.new
+          balance_value = MiniWallet::Balance::Fetch.new(address:, client:).call
+          formatted_balance = format('%.8f', balance_value)
+          balance = "#{formatted_balance} BTC".green.bold
+          puts "Balance for #{address}: #{balance}"
+        end
+      end
+    end
+  end
+end

data/lib/mini_wallet/commands/base.rb

@@ -0,0 +1,32 @@
+require 'dry/cli'
+require 'whirly'
+
+module MiniWallet
+  module Commands
+    class Base < Dry::CLI::Command
+      private
+
+      def ensure_wallet_exists
+        MiniWallet::KeyManager.load_key
+      rescue MiniWallet::KeyManager::WalletNotFoundError
+        puts 'Wallet not found.'.yellow
+        print 'Would you like to create a new wallet now? (y/n): '
+        response = STDIN.gets&.strip&.downcase
+
+        raise Dry::CLI::Error, 'Wallet not initialized. Run `mini_wallet init`.' unless %w[y
+                                                                                           yes].include?(response)
+
+        MiniWallet::Commands::Init.new.call
+        MiniWallet::KeyManager.load_key
+      end
+
+      def with_spinner(status: nil, &block)
+        if ENV['TEST'] == 'true'
+          block.call
+        else
+          Whirly.start(spinner: 'dots7', status:) { block.call }
+        end
+      end
+    end
+  end
+end

data/lib/mini_wallet/commands/init.rb

@@ -0,0 +1,21 @@
+module MiniWallet
+  module Commands
+    class Init < Base
+      desc 'Generates a new Signet wallet (private key + address)'
+
+      def call(*)
+        if MiniWallet::KeyManager.key_file_exists?
+          puts "Wallet already exists at: #{MiniWallet::KeyManager::KEY_FILE}".yellow
+          address = MiniWallet::KeyManager.load_key.to_addr
+          puts "Address: #{address}"
+          return
+        end
+
+        key = MiniWallet::KeyManager.generate_key
+        puts 'New wallet created.'.green.bold
+        puts "Address: #{key.to_addr}".bold
+        puts "Private key saved to: #{MiniWallet::KeyManager::KEY_FILE}"
+      end
+    end
+  end
+end

data/lib/mini_wallet/commands/send.rb

@@ -0,0 +1,39 @@
+module MiniWallet
+  module Commands
+    class Send < Base
+      desc 'Send amount (BTC) to address on Signet'
+
+      argument :to_address, required: true, desc: 'Recipient Bitcoin address'
+      argument :send_amount_btc, required: true, desc: 'Amount BTC to send'
+
+      def call(to_address:, send_amount_btc:)
+        unless Bitcoin.valid_address?(to_address)
+          puts 'Invalid Bitcoin address'.red
+          return
+        end
+
+        key = ensure_wallet_exists
+
+        with_spinner do
+          result = MiniWallet::Tx::Build.new(
+            to_address:,
+            send_amount_btc:,
+            key:,
+            client: Blockstream::Client.new
+          ).call
+
+          if result.failure?
+            puts result.failure.red
+            return
+          end
+
+          tx_hex = result.value!
+          tx_id = Mempool::Client.new.broadcast_transaction(tx_hex)
+
+          puts 'Transaction broadcasted successfully.'
+          puts "Transaction id: #{tx_id.green.bold}..."
+        end
+      end
+    end
+  end
+end

data/lib/mini_wallet/key_manager.rb

@@ -0,0 +1,42 @@
+require 'fileutils'
+
+module MiniWallet
+  class KeyManager
+    KEY_FILE = ENV.fetch('WALLET_KEY_FILE', '.wallet/priv_key.wif').freeze
+    KEY_TYPE = Bitcoin::Key::TYPES[:p2wpkh]
+
+    class WalletNotFoundError < StandardError; end
+
+    class << self
+      def generate_key
+        key = Bitcoin::Key.generate(KEY_TYPE)
+        save_key(key.to_wif)
+        key
+      end
+
+      def load_key
+        raise WalletNotFoundError, 'Init new wallet first.' unless key_file_exists?
+
+        load_key_from_file
+      end
+
+      def key_file_exists?
+        File.exist?(KEY_FILE)
+      end
+
+      private
+
+      def load_key_from_file
+        file = File.read(KEY_FILE).strip
+        Bitcoin::Key.from_wif(file)
+      end
+
+      def save_key(priv_key)
+        dir = File.dirname(KEY_FILE)
+        FileUtils.mkdir_p(dir, mode: 0o700) unless Dir.exist?(dir)
+        File.write(KEY_FILE, priv_key)
+        File.chmod(0o600, KEY_FILE)
+      end
+    end
+  end
+end

data/lib/mini_wallet/tx/build.rb

@@ -0,0 +1,147 @@
+require 'dry/operation'
+require 'dry/initializer'
+require 'bigdecimal'
+
+# Builds and signs Bitcoin transactions using UTXOs from Signet.
+# Handles fee estimation, change output, and SegWit signing.
+module MiniWallet
+  module Tx
+    class Build < Dry::Operation
+      extend Dry::Initializer
+
+      MIN_FEE_SAT = 150
+
+      option :to_address
+      option :send_amount_btc
+      option :key
+      option :client
+
+      def call # rubocop:disable Metrics/AbcSize
+        send_amount_sat = step parse_amount_btc(send_amount_btc)
+        fee_rate = step fetch_fee_rate
+        utxos = step fetch_utxos(key.to_p2wpkh)
+        probe_tx = build_probe_tx_raw(utxos:, to_address:, send_amount_sat:, key:)
+        fee_satoshi = calculate_fee(fee_rate:, vsize: probe_tx.vsize)
+        total_value = step check_balance(utxos:, send_amount_sat:, fee_satoshi:)
+        tx = build_final_tx(utxos:, to_address:, send_amount_sat:, total_value:, fee_satoshi:, key:)
+        signed_tx = step sign_tx_inputs(tx:, utxos:, key:)
+
+        signed_tx.to_hex
+      end
+
+      private
+
+      def parse_amount_btc(input)
+        amount_sat = (BigDecimal(input) * 100_000_000).to_i
+        return Failure('Amount must be positive') if amount_sat <= 0
+
+        Success(amount_sat)
+      rescue ArgumentError
+        Failure('Invalid BTC amount format')
+      end
+
+      def fetch_fee_rate
+        rate = client.fetch_fee_rate
+
+        if rate.is_a?(Numeric) && rate.positive?
+          Success(rate.to_i)
+        else
+          Success(1)
+        end
+      rescue StandardError => e
+        warn "Failed to fetch fee rate: #{e.message}. Using fallback rate 1 sat/vB."
+        Success(1)
+      end
+
+      def fetch_utxos(address)
+        utxos = client.fetch_utxos(address)
+        return Failure('No UTXOs available') if utxos.empty?
+
+        Success(utxos)
+      rescue StandardError => e
+        Failure("Failed to fetch UTXOs: #{e.message}")
+      end
+
+      def calculate_fee(fee_rate:, vsize:)
+        dynamic = fee_rate * vsize
+        [dynamic, MIN_FEE_SAT].max
+      end
+
+      def build_probe_tx_raw(utxos:, to_address:, send_amount_sat:, key:)
+        tx = Bitcoin::Tx.new
+        tx = add_inputs_raw(tx:, utxos:)
+        tx = add_output_raw(tx:, to_address:, value: send_amount_sat)
+
+        change_script = Bitcoin::Script.parse_from_addr(key.to_p2wpkh)
+        tx.out << Bitcoin::TxOut.new(value: 1, script_pubkey: change_script)
+        tx
+      end
+
+      def check_balance(utxos:, send_amount_sat:, fee_satoshi:)
+        total = utxos.sum { _1['value'] }
+        required = send_amount_sat + fee_satoshi
+
+        if total >= required
+          Success(total)
+        else
+          balance_btc = BigDecimal(total) / 100_000_000
+          required_btc = BigDecimal(required) / 100_000_000
+          Failure(
+            "Insufficient funds: balance #{'%.8f' % balance_btc} BTC, " \
+            "required #{'%.8f' % required_btc} BTC (fee: #{fee_satoshi} sat)"
+          )
+        end
+      end
+
+      def build_final_tx(utxos:, to_address:, send_amount_sat:, total_value:, fee_satoshi:, key:)
+        tx = Bitcoin::Tx.new
+        add_inputs_raw(tx:, utxos: utxos)
+        add_output_raw(tx:, to_address:, value: send_amount_sat)
+
+        change_sat = total_value - (send_amount_sat + fee_satoshi)
+        add_output_raw(tx:, to_address: key.to_p2wpkh, value: change_sat) if change_sat.positive?
+
+        tx
+      end
+
+      def add_inputs_raw(tx:, utxos:)
+        utxos.each do |utxo|
+          out_point = Bitcoin::OutPoint.from_txid(utxo['txid'], utxo['vout'])
+          tx.in << Bitcoin::TxIn.new(out_point: out_point)
+        end
+        tx
+      end
+
+      def add_output_raw(tx:, to_address:, value:)
+        script = Bitcoin::Script.parse_from_addr(to_address)
+        tx.out << Bitcoin::TxOut.new(value:, script_pubkey: script)
+        tx
+      end
+
+      def fetch_prev_script_pub_key(txid:, vout:)
+        tx_hex = client.fetch_transaction_hex(txid)
+        script = Bitcoin::Tx
+                 .parse_from_payload([tx_hex].pack('H*'))
+                 .out[vout]
+                 .script_pubkey
+        Success(script)
+      end
+
+      def sign_tx_inputs(tx:, utxos:, key:)
+        utxos.each_with_index do |utxo, index|
+          script_pubkey = step fetch_prev_script_pub_key(txid: utxo['txid'], vout: utxo['vout'])
+
+          sig_hash = tx.sighash_for_input(index, script_pubkey, sig_version: :witness_v0, amount: utxo['value'])
+          signature = key.sign(sig_hash) + [Bitcoin::SIGHASH_TYPE[:all]].pack('C')
+
+          tx.in[index].script_witness.stack.concat([signature, key.pubkey.htb])
+
+          unless tx.verify_input_sig(index, script_pubkey, amount: utxo['value'])
+            return Failure("ScriptPubkey verification failed for txid #{utxo['txid']}")
+          end
+        end
+        Success(tx)
+      end
+    end
+  end
+end

data/lib/mini_wallet/version.rb

@@ -0,0 +1,3 @@
+module MiniWallet
+  VERSION = '0.1.0'
+end

data/lib/mini_wallet.rb

@@ -0,0 +1,6 @@
+require 'bitcoin'
+
+Bitcoin.chain_params = :signet
+
+module MiniWallet
+end

metadata

@@ -0,0 +1,195 @@
+--- !ruby/object:Gem::Specification
+name: mini-wallet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ilmir
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bitcoin-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: dry-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: dry-initializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: dry-operation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: whirly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.25.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.25.1
+description: Generate keys, check balance, and send transactions on Bitcoin Signet.
+email:
+- code.for.func@gmail.com
+executables:
+- mini_wallet
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/mini_wallet
+- lib/blockstream/client.rb
+- lib/mempool/client.rb
+- lib/mini_wallet.rb
+- lib/mini_wallet/balance/fetch.rb
+- lib/mini_wallet/cli.rb
+- lib/mini_wallet/commands/balance.rb
+- lib/mini_wallet/commands/base.rb
+- lib/mini_wallet/commands/init.rb
+- lib/mini_wallet/commands/send.rb
+- lib/mini_wallet/key_manager.rb
+- lib/mini_wallet/tx/build.rb
+- lib/mini_wallet/version.rb
+homepage: https://gitlab.com/i-karimov/mini_wallet
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: A minimal Bitcoin wallet CLI for Testnet
+test_files: []