pwn 0.5.749 → 0.5.751

data/spec/lib/pwn/blockchain/btc_spec.rb

@@ -2,7 +2,378 @@
 
 require 'spec_helper'
 
-describe PWN::Blockchain::BTC do
+describe PWN::Blockchain::BTC do # rubocop:disable Metrics/BlockLength
+  let(:config) { { rpc_host: 'localhost', rpc_port: 8332, rpc_user: 'alice', rpc_pass: 'secret' }.freeze }
+  let(:http) { instance_double(Net::HTTP) }
+
+  before do
+    stub_const('PWN::Env', { plugins: { blockchain: { bitcoin: config } } })
+    allow(Net::HTTP).to receive(:new).and_return(http)
+    allow(http).to receive(:open_timeout=)
+    allow(http).to receive(:read_timeout=)
+    allow(http).to receive(:write_timeout=)
+    allow(http).to receive(:use_ssl=)
+    allow(http).to receive(:verify_mode=)
+  end
+
+  def rpc_response(result: nil, error: nil, status: '200')
+    double('response', code: status, body: JSON.generate(result: result, error: error, id: 'pwn-btc'))
+  end
+
+  it 'returns the legacy envelope silently without AI or config mutation' do
+    allow(http).to receive(:request).and_return(rpc_response(result: { blocks: 10 }))
+    expect { expect(described_class.get_latest_block[:result]).to eq(blocks: 10) }.not_to output.to_stdout
+  end
+
+  it 'preserves HTTP 500 RPC error codes without echoing server secrets' do
+    allow(http).to receive(:request).and_return(rpc_response(error: { code: -5, message: 'secret alice' }, status: '500'))
+    expect { described_class.get_latest_block }.to raise_error(described_class::RPCError) { |e|
+      expect(e.code).to eq(-5)
+      expect(e.http_status).to eq(500)
+      expect(e.message).not_to include('secret', 'alice')
+    }
+  end
+
+  it 'uses verified TLS, bounded timeouts and authenticated POST' do
+    config = self.config.merge(rpc_scheme: 'https')
+    stub_const('PWN::Env', { plugins: { blockchain: { bitcoin: config } } })
+    expect(http).to receive(:use_ssl=).with(true)
+    expect(http).to receive(:verify_mode=).with(OpenSSL::SSL::VERIFY_PEER)
+    expect(http).to receive(:read_timeout=).with(30)
+    expect(http).to receive(:request) do |request|
+      expect(request).to be_a(Net::HTTP::Post)
+      expect(JSON.parse(request.body)['method']).to eq('getblockchaininfo')
+      rpc_response(result: { blocks: 0 })
+    end
+    described_class.get_latest_block
+  end
+
+  it 'sanitizes transport failures and suppresses their causes' do
+    allow(http).to receive(:request).and_raise(IOError, 'secret alice')
+    expect { described_class.get_latest_block }.to raise_error(described_class::RPCError) { |e|
+      expect(e.message).not_to include('secret', 'alice')
+      expect(e.cause).to be_nil
+    }
+  end
+  let(:txid) { 'a' * 64 }
+  let(:parent_id) { 'b' * 64 }
+  let(:blockhash) { 'c' * 64 }
+  let(:parent_tx) { { txid: parent_id, vin: [{ coinbase: '00' }], vout: [{ n: 0, value: '0.10000001', scriptPubKey: { address: 'test' } }] } }
+  let(:transaction) { { txid: txid, vin: [{ txid: parent_id, vout: 0 }], vout: [{ n: 0, value: '0.10000000', scriptPubKey: { address: 'test' } }] } }
+
+  def serve_rpc(&block)
+    allow(http).to receive(:request) do |request|
+      payload = JSON.parse(request.body, symbolize_names: true)
+      result = block.call(payload[:method], payload[:params])
+      rpc_response(result: result)
+    end
+  end
+
+  it 'inspects exact satoshis, resolves prevouts and computes fees only with evidence' do
+    serve_rpc do |method, params|
+      expect(method).to eq('getrawtransaction')
+      params.first == txid ? transaction : parent_tx
+    end
+    result = described_class.inspect_transaction(txid: txid)
+    expect(result[:outputs].first[:value_sats]).to eq(10_000_000)
+    expect(result[:inputs].first[:value_sats]).to eq(10_000_001)
+    expect(result[:fee_sats]).to eq(1)
+    expect(result[:missing_prevouts]).to be_empty
+  end
+
+  it 'reports unavailable prevouts, does not invent fees and bounds lookups' do
+    serve_rpc { transaction }
+    result = described_class.inspect_transaction(txid: txid, max_prevouts: 0)
+    expect(result[:fee_sats]).to be_nil
+    expect(result[:missing_prevouts]).to eq([{ txid: parent_id, vout: 0, reason: :lookup_limit }])
+    expect(http).to have_received(:request).once
+  end
+
+  it 'passes an optional block hash for non-indexed transaction lookup' do
+    serve_rpc do |_method, params|
+      expect(params).to eq([txid, true, blockhash])
+      transaction.merge(vin: [{ coinbase: '00' }])
+    end
+    result = described_class.inspect_transaction(txid: txid, blockhash: blockhash)
+    expect(result[:coinbase]).to be(true)
+    expect(result[:fee_sats]).to be_nil
+  end
+
+  it 'does not hide authentication errors as missing transactions' do
+    allow(http).to receive(:request).and_return(rpc_response(result: transaction), rpc_response(error: { code: -32_600 }, status: '401'))
+    expect { described_class.inspect_transaction(txid: txid) }.to raise_error(described_class::RPCError)
+  end
+
+  it 'inspects an unspent outpoint and distinguishes null from proof of spending' do
+    serve_rpc do |method, params|
+      expect(method).to eq('gettxout')
+      expect(params).to eq([txid, 0, false])
+      { value: '0.00000001', confirmations: 4 }
+    end
+    expect(described_class.inspect_outpoint(txid: txid, vout: 0, include_mempool: false)[:value_sats]).to eq(1)
+    serve_rpc { nil }
+    expect(described_class.inspect_outpoint(txid: txid, vout: 0)).to include(status: :spent_or_unknown, unspent: false)
+  end
+
+  it 'reads mempool statistics without fetching all transactions' do
+    serve_rpc do |method, params|
+      expect([method, params]).to eq(['getmempoolinfo', []])
+      { size: 10, bytes: 2345, loaded: true }
+    end
+    expect(described_class.mempool_summary[:size]).to eq(10)
+  end
+
+  it 'rejects malformed identifiers, indices and flags before issuing RPC' do
+    expect(http).not_to receive(:request)
+    expect { described_class.inspect_transaction(txid: 'bad') }.to raise_error(ArgumentError)
+    expect { described_class.inspect_outpoint(txid: txid, vout: '0') }.to raise_error(ArgumentError)
+    expect { described_class.inspect_outpoint(txid: txid, vout: 0, include_mempool: 'false') }.to raise_error(ArgumentError)
+    expect { described_class.get_block_details(height: -1) }.to raise_error(ArgumentError)
+    expect { described_class.get_block_details(height: 0, verbosity: 4) }.to raise_error(ArgumentError)
+  end
+
+  it 'traces ancestors with spend-reference evidence and exact values' do
+    serve_rpc { |_method, params| params.first == txid ? transaction : parent_tx }
+    result = described_class.trace_transaction(txid: txid)
+    expect(result[:nodes].map { |node| node[:txid] }).to eq([txid, parent_id])
+    expect(result[:edges]).to eq([{ from_txid: parent_id, from_vout: 0, to_txid: txid, to_vin: 0, value_sats: 10_000_001, evidence: :vin_reference }])
+    expect(result[:complete]).to be(true)
+    expect(http).to have_received(:request).twice
+  end
+
+  it 'reports depth and transaction limits without fetching beyond either bound' do
+    serve_rpc { transaction }
+    result = described_class.trace_transaction(txid: txid, max_depth: 0)
+    expect(result).to include(complete: false, truncated: true)
+    expect(result[:truncation_reasons]).to include(:max_depth)
+    expect(result[:missing_prevouts].first).to include(txid: parent_id, vout: 0)
+    expect(http).to have_received(:request).once
+  end
+
+  it 'bounds edges and reports omitted input evidence explicitly' do
+    serve_rpc { transaction.merge(vin: [{ txid: parent_id, vout: 0 }, { txid: parent_id, vout: 1 }]) }
+    result = described_class.trace_transaction(txid: txid, max_edges: 1, max_transactions: 1)
+    expect(result[:edges].length).to eq(1)
+    expect(result[:truncation_reasons]).to include(:max_edges, :max_transactions)
+    expect(http).to have_received(:request).once
+  end
+
+  it 'reports unavailable ancestors rather than claiming a complete trace' do
+    allow(http).to receive(:request).and_return(rpc_response(result: transaction), rpc_response(error: { code: -5 }, status: '500'))
+    result = described_class.trace_transaction(txid: txid)
+    expect(result[:complete]).to be(false)
+    expect(result[:missing_transactions]).to eq([{ txid: parent_id, code: -5 }])
+    expect(result[:missing_prevouts].first[:reason]).to eq(:unavailable)
+  end
+
+  def serve_chain(times:, transactions: nil, reorg: false)
+    anchor_reads = 0
+    serve_rpc do |method, params|
+      case method
+      when 'getblockchaininfo' then { blocks: times.length - 1, bestblockhash: blockhash, chain: 'regtest' }
+      when 'getblockhash'
+        anchor_reads += 1 if params.first == times.length - 1
+        reorg && anchor_reads > 2 ? 'f' * 64 : format('%064x', params.first)
+      when 'getblock'
+        height = params.first.to_i(16)
+        { hash: params.first, height: height, previousblockhash: format('%064x', height - 1), time: times[height], tx: transactions || [format('%064x', height + 100)] }
+      when 'validateaddress' then { isvalid: true, scriptPubKey: '76a91400' }
+      else raise "Unexpected RPC #{method}"
+      end
+    end
+  end
+
+  it 'scans every explicit height despite nonmonotonic timestamps and uses UTC days' do
+    serve_chain(times: [1_704_067_200, 1_704_240_000, 1_704_067_210])
+    result = described_class.scan_transactions(from: '2024-01-01', to: '2024-01-01', start_height: 0, end_height: 2)
+    expect(result[:transactions].map { |tx| tx[:height] }).to eq([0, 2])
+    expect(result).to include(complete: true, next_height: nil, reorg_detected: false)
+    expect(result[:blocks].length).to eq(3)
+    expect(result[:scope]).to eq(:explicit_height_range)
+  end
+
+  it 'returns bounded pages with explicit continuation instead of silently omitting dates' do
+    serve_chain(times: [1_704_067_200] * 3)
+    result = described_class.scan_transactions(from: '2024-01-01', to: '2024-01-01', start_height: 0, end_height: 2, max_blocks: 1)
+    expect(result).to include(complete: false, truncated: true, next_height: 1)
+    expect(result[:transactions].length).to eq(1)
+  end
+
+  it 'preserves the legacy array only for a fully scanned explicit range' do
+    serve_chain(times: [1_704_067_200])
+    expect(described_class.get_transactions(from: '2024-01-01', to: '2024-01-01', start_height: 0, end_height: 0)).to eq([format('%064x', 100)])
+    expect { described_class.get_transactions(from: '2024-01-01', to: '2024-01-01') }.to raise_error(ArgumentError)
+    expect { described_class.get_transactions(from: '2024-01-01', to: '2024-01-01', start_height: 0, end_height: 2, max_blocks: 1) }.to raise_error(ArgumentError)
+  end
+
+  it 'detects anchor changes and never labels reorganized scans complete' do
+    serve_chain(times: [1_704_067_200], reorg: true)
+    result = described_class.scan_transactions(from: '2024-01-01', to: '2024-01-01', start_height: 0, end_height: 0)
+    expect(result).to include(reorg_detected: true, complete: false)
+  end
+
+  it 'requires strict dates and explicit integer height ranges before RPC' do
+    expect(http).not_to receive(:request)
+    expect { described_class.scan_transactions(from: '2024-02-30', to: '2024-03-01', start_height: 0, end_height: 1) }.to raise_error(ArgumentError)
+    expect { described_class.scan_transactions(from: '2024-01-02', to: '2024-01-01', start_height: 0, end_height: 1) }.to raise_error(ArgumentError)
+    expect { described_class.scan_transactions(from: '2024-01-01', to: '2024-01-01') }.to raise_error(ArgumentError)
+  end
+
+  it 'scans address scripts with receive and spend evidence, not an address index' do
+    parent = parent_tx.merge(vout: [{ n: 0, value: '0.10000001', scriptPubKey: { hex: '76a91400' } }])
+    spend = transaction.merge(vout: [{ n: 0, value: '0.10000000', scriptPubKey: { hex: 'other' } }])
+    serve_chain(times: [1_704_067_200], transactions: [parent, spend])
+    result = described_class.scan_address_activity(address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', start_height: 0, end_height: 0, max_prevouts: 0)
+    expect(result[:activity].map { |event| event[:type] }).to eq(%i[received spent])
+    expect(result[:activity].map { |event| event[:value_sats] }).to eq([10_000_001, 10_000_001])
+    expect(result[:complete]).to be(true)
+    expect(result[:address_index]).to be(false)
+  end
+
+  it 'uses undo-rich blocks without spending the available parent lookup budget' do
+    prevout = { value: '0.10000001', scriptPubKey: { hex: '76a91400' } }
+    spend = transaction.merge(vin: [{ txid: parent_id, vout: 0, prevout: prevout }])
+    serve_chain(times: [1_704_067_200], transactions: [spend])
+    expect(described_class).to receive(:get_block_details).with({ height: 0, verbosity: 3, timeout: 30 }).and_call_original
+    result = described_class.scan_address_activity(address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', start_height: 0, end_height: 0, max_prevouts: 5)
+    expect(result).to include(complete: true, missing_prevouts: [])
+    expect(result[:activity]).to include(include(type: :spent, value_sats: 10_000_001, prev_txid: parent_id))
+    expect(http).to have_received(:request).exactly(7).times
+  end
+
+  [-8, -32_602].each do |code|
+    it "falls back to verbosity 2 for older-node parameter error #{code}" do
+      parent = parent_tx.merge(vout: [{ n: 0, value: '0.10000001', scriptPubKey: { hex: '76a91400' } }])
+      serve_chain(times: [1_704_067_200], transactions: [parent, transaction])
+      allow(described_class).to receive(:btc_rpc_call).and_wrap_original do |original, opts|
+        raise described_class::RPCError.new(rpc_method: 'getblock', code: code, http_status: 500) if opts[:method] == 'getblock' && opts[:params].last == 3
+
+        original.call(opts)
+      end
+      result = described_class.scan_address_activity(address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', start_height: 0, end_height: 0, max_prevouts: 0)
+      expect(result).to include(complete: true, missing_prevouts: [])
+      expect(result[:activity].map { |event| event[:type] }).to eq(%i[received spent])
+      expect(described_class).to have_received(:btc_rpc_call).with(method: 'getblock', params: [format('%064x', 0), 2], timeout: 30).once
+    end
+  end
+
+  it 'does not downgrade unavailable undo data into a successful address scan' do
+    serve_chain(times: [1_704_067_200], transactions: [transaction])
+    allow(described_class).to receive(:btc_rpc_call).and_wrap_original do |original, opts|
+      if opts[:method] == 'getblock'
+        expect(opts[:params].last).to eq(3)
+        raise described_class::RPCError.new(rpc_method: 'getblock', code: -1, http_status: 500)
+      end
+
+      original.call(opts)
+    end
+    result = described_class.scan_address_activity(address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', start_height: 0, end_height: 0)
+    expect(result).to include(complete: false, missing_blocks: [{ height: 0, code: -1 }])
+  end
+
+  it 'reports unknown address spends when parent data is missing' do
+    serve_chain(times: [1_704_067_200], transactions: [transaction])
+    result = described_class.scan_address_activity(address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', start_height: 0, end_height: 0, max_prevouts: 0)
+    expect(result[:complete]).to be(false)
+    expect(result[:missing_prevouts].first).to include(txid: parent_id, reason: :lookup_limit)
+  end
+
+  it 'accepts uppercase hashes without losing trace evidence or rewriting the RPC token' do
+    serve_rpc do |_method, params|
+      expect(params.first).to eq(txid.upcase)
+      transaction
+    end
+    result = described_class.trace_transaction(txid: txid.upcase, max_depth: 0)
+    expect(result[:edges].first[:to_txid]).to eq(txid)
+  end
+
+  it 'decodes JSON numeric amounts without a Float roundtrip' do
+    body = JSON.generate(result: transaction.merge(vin: [{ coinbase: '00' }]), error: nil, id: 'pwn-btc').sub('"0.10000000"', '20999999.99999999')
+    allow(http).to receive(:request).and_return(double('response', code: '200', body: body))
+    expect(described_class.inspect_transaction(txid: txid)[:output_sats]).to eq(2_099_999_999_999_999)
+  end
+
+  it 'rejects sub-satoshi values rather than rounding them' do
+    bad = transaction.merge(vin: [{ coinbase: '00' }], vout: [{ n: 0, value: '0.000000001' }])
+    serve_rpc { bad }
+    expect { described_class.inspect_transaction(txid: txid) }.to raise_error(described_class::RPCError, /invalid monetary/)
+  end
+
+  it 'reuses a single parent lookup across several inputs' do
+    parent = parent_tx.merge(vout: [{ n: 0, value: '0.10000001' }, { n: 1, value: '0.2' }])
+    spend = transaction.merge(vin: [{ txid: parent_id, vout: 0 }, { txid: parent_id, vout: 1 }])
+    serve_rpc { |_method, params| params.first == txid ? spend : parent }
+    expect(described_class.inspect_transaction(txid: txid, max_prevouts: 1)[:input_sats]).to eq(30_000_001)
+    expect(http).to have_received(:request).twice
+  end
+
+  it 'returns pruning gaps as incomplete date evidence and raises in legacy array mode' do
+    serve_chain(times: [1_704_067_200])
+    allow(described_class).to receive(:get_block_details).and_raise(described_class::RPCError.new(code: -1, http_status: 500))
+    opts = { from: '2024-01-01', to: '2024-01-01', start_height: 0, end_height: 0 }
+    result = described_class.scan_transactions(opts)
+    expect(result).to include(complete: false, missing_blocks: [{ height: 0, code: -1 }])
+    expect { described_class.get_transactions(opts) }.to raise_error(described_class::RPCError, /incomplete scan/)
+  end
+
+  it 'returns block serialization or transaction verbosity as explicitly requested' do
+    [0, 1, 2, 3].each do |verbosity|
+      serve_rpc do |method, params|
+        if method == 'getblockhash'
+          expect(params).to eq([0])
+          blockhash
+        else
+          expect(params).to eq([blockhash, verbosity])
+          verbosity.zero? ? 'deadbeef' : { hash: blockhash, tx: [] }
+        end
+      end
+      result = described_class.get_block_details(height: 0, verbosity: verbosity)
+      expect(result).to eq(verbosity.zero? ? 'deadbeef' : { hash: blockhash, tx: [] })
+    end
+  end
+
+  it 'rejects malformed JSON, mismatched IDs and non-JSON HTTP failures without leaking bodies' do
+    ['secret alice', '{"id":"other","result":"secret"}', '[]'].each do |body|
+      allow(http).to receive(:request).and_return(double('response', code: '503', body: body))
+      expect { described_class.get_latest_block }.to raise_error(described_class::RPCError) { |e|
+        expect(e.http_status).to eq(503)
+        expect(e.message).not_to include('secret', 'alice')
+        expect(e.cause).to be_nil
+      }
+    end
+  end
+
+  it 'rejects absent credentials, unsafe hosts, invalid ports and timeouts without connecting' do
+    expect(http).not_to receive(:request)
+    [config.merge(rpc_pass: nil), config.merge(rpc_host: 'http://secret@host'), config.merge(rpc_port: '8332oops')].each do |invalid|
+      stub_const('PWN::Env', { plugins: { blockchain: { bitcoin: invalid.freeze } } })
+      expect { described_class.get_latest_block }.to raise_error(ArgumentError)
+    end
+    stub_const('PWN::Env', { plugins: { blockchain: { bitcoin: config } } })
+    expect { described_class.chain_status(timeout: 0) }.to raise_error(ArgumentError)
+    expect { described_class.chain_status(timeout: '30') }.to raise_error(ArgumentError)
+  end
+
+  it 'rejects write RPCs even at the private transport boundary' do
+    expect(http).not_to receive(:request)
+    expect { described_class.send(:btc_rpc_call, method: 'sendrawtransaction', params: ['00']) }.to raise_error(ArgumentError)
+  end
+
+  it 'sanitizes connection setup exceptions as well as request failures' do
+    allow(Net::HTTP).to receive(:new).and_raise(IOError, 'secret alice')
+    expect { described_class.get_latest_block }.to raise_error(described_class::RPCError) { |e|
+      expect(e.message).not_to include('secret', 'alice')
+      expect(e.cause).to be_nil
+    }
+  end
+
+  it 'enforces a total request deadline even when a peer keeps dribbling data' do
+    allow(http).to receive(:request) { sleep 2 }
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    expect { described_class.chain_status(timeout: 1) }.to raise_error(described_class::RPCError, /transport/)
+    expect(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).to be < 1.8
+  end
+
   it 'should display information for authors' do
     authors_response = PWN::Blockchain::BTC
     expect(authors_response).to respond_to :authors

data/spec/lib/pwn/blockchain/eth_spec.rb

@@ -3,6 +3,211 @@
 require 'spec_helper'
 
 describe PWN::Blockchain::ETH do
+  let(:rpc_opts) { { rpc_url: 'https://node.example/secret' } }
+  let(:address) { "0x#{'ab' * 20}" }
+  let(:tx_hash) { "0x#{'cd' * 32}" }
+  let(:transfer_topic) { '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef' }
+  let(:transfer_log) do
+    { address: address, topics: [transfer_topic, "0x#{'0' * 24}#{address[2..]}", "0x#{'0' * 64}"], data: "0x#{'0' * 63}7", blockNumber: '0x1', transactionHash: tx_hash }
+  end
+
+  it 'preserves BlockCypher APIs and token with verified TLS' do
+    allow(RestClient::Request).to receive(:execute) do |request|
+      expect(request[:verify_ssl]).to eq(OpenSSL::SSL::VERIFY_PEER)
+      expect(request[:headers][:params]).to eq(token: 'token')
+      double(body: '{"height":123}')
+    end
+    expect(described_class.get_latest_block(token: 'token')).to eq(height: 123)
+    expect(described_class.get_block_details(height: 123, token: 'token')).to eq(height: 123)
+    expect { described_class.get_block_details(height: '../bad') }.to raise_error(ArgumentError)
+  end
+
+  it 'redacts HTTP failures and JSON RPC provider messages including causes' do
+    allow(RestClient::Request).to receive(:execute).and_raise(RestClient::Forbidden.new)
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, 'Ethereum HTTP transport failed') { |error| expect(error.cause).to be_nil }
+    allow(RestClient::Request).to receive(:execute).and_return(double(body: '{"jsonrpc":"2.0","id":1,"error":{"message":"secret"}}'))
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, 'JSON-RPC provider returned an error')
+  end
+
+  it 'rejects bad envelopes, invalid quantities and invalid endpoints' do
+    allow(RestClient::Request).to receive(:execute).and_return(double(body: 'not json'))
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, /JSON response/)
+    allow(RestClient::Request).to receive(:execute).and_return(double(body: '{"jsonrpc":"2.0","id":2,"result":1}'))
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, /envelope/)
+    stub_rpc('eth_chainId' => '0x01')
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, /quantity/)
+    expect { described_class.chain_status(rpc_url: 'file:///secret') }.to raise_error(ArgumentError)
+  end
+
+  it 'marks reverted receipts and does not infer success from inclusion alone' do
+    stub_rpc('eth_getTransactionByHash' => { hash: tx_hash, value: '0x0', blockNumber: '0x1' },
+             'eth_getTransactionReceipt' => { transactionHash: tx_hash, status: '0x0' })
+    expect(described_class.transaction(rpc_opts.merge(hash: tx_hash))[:status]).to eq(:reverted)
+    stub_rpc('eth_getTransactionByHash' => { hash: tx_hash, value: '0x0', blockNumber: '0x1' }, 'eth_getTransactionReceipt' => nil)
+    expect(described_class.transaction(rpc_opts.merge(hash: tx_hash))[:status]).to eq(:receipt_unavailable)
+  end
+
+  it 'decodes only standard Transfer layouts without claiming contract conformance' do
+    expect(described_class.decode_transfer(log: transfer_log)).to include(standard: :erc20, value: 7, from: address)
+    nft = transfer_log.merge(topics: transfer_log[:topics] + ["0x#{'0' * 63}9"], data: '0x')
+    expect(described_class.decode_transfer(log: nft)).to include(standard: :erc721, token_id: 9)
+    expect(described_class.decode_transfer(log: transfer_log.merge(topics: [tx_hash]))).to be_nil
+    expect { described_class.decode_transfer(log: transfer_log.merge(data: '0x01')) }.to raise_error(ArgumentError)
+    expect { described_class.decode_transfer(log: transfer_log.merge(topics: [transfer_topic, tx_hash, tx_hash])) }.to raise_error(ArgumentError)
+  end
+
+  it 'bounds logs and reports local truncation without provider completeness guarantees' do
+    stub_rpc('eth_getLogs' => [transfer_log, transfer_log])
+    result = described_class.event_logs(rpc_opts.merge(from_block: 1, to_block: 2, limit: 1))
+    expect(result).to include(truncated: true, complete: false, provider_completeness: :unverified)
+    expect(result[:logs].length).to eq(1)
+    expect { described_class.event_logs(rpc_opts.merge(from_block: 0, to_block: 10_001)) }.to raise_error(ArgumentError)
+  end
+
+  it 'paginates address activity by whole blocks and excludes traces explicitly' do
+    stub_rpc('eth_getBlockByNumber' => { number: '0x1', hash: tx_hash, transactions: [{ hash: tx_hash, from: address, to: nil, value: '0x1' }] })
+    result = described_class.address_activity(rpc_opts.merge(address: address, from_block: 1, to_block: 2, page_size: 1))
+    expect(result).to include(next_block: 2, complete: false, internal_traces: :not_covered)
+    expect(result[:transactions].length).to eq(1)
+  end
+
+  it 'rejects malformed unknown-event topics and out-of-range provider logs' do
+    stub_rpc('eth_getLogs' => [transfer_log.merge(topics: ['0xbad'])])
+    expect { described_class.event_logs(rpc_opts.merge(from_block: 1, to_block: 2)) }.to raise_error(ArgumentError)
+    stub_rpc('eth_getLogs' => [transfer_log.merge(blockNumber: '0x3')])
+    expect { described_class.event_logs(rpc_opts.merge(from_block: 1, to_block: 2)) }.to raise_error(described_class::RPCError)
+  end
+
+  it 'redacts malformed legacy response bodies and timeout details' do
+    allow(RestClient::Request).to receive(:execute).and_return(double(body: 'secret-invalid-json'))
+    expect { described_class.get_latest_block }.to raise_error(described_class::RPCError, 'Invalid BlockCypher JSON response') { |error| expect(error.cause).to be_nil }
+    allow(RestClient::Request).to receive(:execute).and_raise(Timeout::Error, 'https://node.example/secret')
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, 'Ethereum HTTP transport failed')
+  end
+
+  it 'rejects mismatched block identities and receipt inclusion contexts' do
+    stub_rpc('eth_getBlockByNumber' => { number: '0x2', hash: tx_hash })
+    expect { described_class.block(rpc_opts.merge(block: 1)) }.to raise_error(described_class::RPCError)
+    stub_rpc('eth_getTransactionByHash' => { hash: tx_hash, value: '0x0', blockNumber: '0x1', blockHash: tx_hash },
+             'eth_getTransactionReceipt' => { transactionHash: tx_hash, status: '0x1', blockNumber: '0x2', blockHash: tx_hash })
+    expect { described_class.transaction(rpc_opts.merge(hash: tx_hash)) }.to raise_error(described_class::RPCError)
+  end
+
+  it 'resumes activity without duplicates and states when the requested range is exhausted' do
+    allow(RestClient::Request).to receive(:execute) do |request|
+      payload = JSON.parse(request[:payload])
+      height = payload['params'][0]
+      double(body: JSON.generate(jsonrpc: '2.0', id: 1, result: { number: height, hash: tx_hash, transactions: [] }))
+    end
+    page = described_class.address_activity(rpc_opts.merge(address: address, from_block: 1, to_block: 2, page_size: 1))
+    last = described_class.address_activity(rpc_opts.merge(address: address, from_block: page[:next_block], to_block: 2, page_size: 1))
+    expect(last).to include(complete: true, next_block: nil, from_block: 2)
+  end
+
+  it 'reads token metadata at a common block with optional unsupported fields' do
+    allow(RestClient::Request).to receive(:execute) do |request|
+      payload = JSON.parse(request[:payload])
+      result = if payload['method'] == 'eth_getBlockByNumber'
+                 { number: '0x1', hash: tx_hash }
+               else
+                 expect(payload['params'][1]).to eq('blockHash' => tx_hash, 'requireCanonical' => true)
+                 case payload['params'][0]['data']
+                 when '0x313ce567' then "0x#{18.to_s(16).rjust(64, '0')}"
+                 when '0x18160ddd' then "0x#{'f' * 64}"
+                 when '0x95d89b41' then "0x#{'TOK'.unpack1('H*').ljust(64, '0')}"
+                 else '0x'
+                 end
+               end
+      double(body: JSON.generate(jsonrpc: '2.0', id: 1, result: result))
+    end
+    result = described_class.token_metadata(rpc_opts.merge(contract: address))
+    expect(result).to include(decimals: 18, symbol: 'TOK', total_supply: (2**256) - 1, name: nil)
+    expect(result[:unavailable]).to include(:name)
+  end
+
+  it 'performs a pinned read-only contract call with exact byte output' do
+    stub_rpc('eth_getBlockByNumber' => { number: '0x1', hash: tx_hash }, 'eth_call' => '0x0001')
+    expect(described_class.call(rpc_opts.merge(contract: address, data: '0x18160ddd'))).to include(data: '0x0001', block_hash: tx_hash)
+  end
+
+  it 'inspects a mined transaction with exact execution and blob fees' do
+    stub_rpc('eth_getTransactionByHash' => { hash: tx_hash, from: address, to: nil, value: '0x20000000000001', blockNumber: '0x10' },
+             'eth_getTransactionReceipt' => { transactionHash: tx_hash, status: '0x1', gasUsed: '0x5208', effectiveGasPrice: '0x100000000', blobGasUsed: '0x2', blobGasPrice: '0x3', contractAddress: address })
+    result = described_class.transaction(rpc_opts.merge(hash: tx_hash))
+    expect(result).to include(status: :success, value_wei: 9_007_199_254_740_993, execution_fee_wei: 90_194_313_216_000, blob_fee_wei: 6, contract_address: address, internal_traces: :not_covered)
+  end
+
+  it 'distinguishes pending and unknown transactions' do
+    stub_rpc('eth_getTransactionByHash' => { hash: tx_hash, value: '0x0', blockNumber: nil }, 'eth_getTransactionReceipt' => nil)
+    expect(described_class.transaction(rpc_opts.merge(hash: tx_hash))[:status]).to eq(:pending)
+    stub_rpc('eth_getTransactionByHash' => nil)
+    expect(described_class.transaction(rpc_opts.merge(hash: tx_hash))[:status]).to eq(:not_found)
+  end
+
+  it 'reads a block by hash and an account at an explicit block context' do
+    stub_rpc('eth_getBlockByHash' => { hash: tx_hash, number: '0x10' },
+             'eth_getBlockByNumber' => { hash: tx_hash, number: '0x10' },
+             'eth_getBalance' => '0x20000000000001', 'eth_getTransactionCount' => '0x3', 'eth_getCode' => '0x6000')
+    expect(described_class.block(rpc_opts.merge(block: tx_hash))[:block][:hash]).to eq(tx_hash)
+    expect(described_class.account(rpc_opts.merge(address: address))).to include(balance_wei: 9_007_199_254_740_993, nonce: 3, code: '0x6000', block_number: 16, block_hash: tx_hash)
+  end
+
+  it 'rejects malformed identifiers before transport' do
+    expect(RestClient::Request).not_to receive(:execute)
+    expect { described_class.transaction(rpc_opts.merge(hash: '0xabc')) }.to raise_error(ArgumentError)
+    expect { described_class.account(rpc_opts.merge(address: "#{address} ")) }.to raise_error(ArgumentError)
+    expect { described_class.block(rpc_opts.merge(block: -1)) }.to raise_error(ArgumentError)
+  end
+
+  def stub_rpc(results)
+    allow(RestClient::Request).to receive(:execute) do |request|
+      payload = JSON.parse(request[:payload])
+      expect(request[:method]).to eq(:post)
+      expect(request[:max_redirects]).to eq(0)
+      expect(request[:timeout]).to eq(30)
+      expect(request[:verify_ssl]).to eq(OpenSSL::SSL::VERIFY_PEER)
+      expect(request[:open_timeout]).to eq(10)
+      result = results.fetch(payload.fetch('method'))
+      double(body: JSON.generate(jsonrpc: '2.0', id: 1, result: result))
+    end
+  end
+
+  it 'reads chain status through verified read-only JSON RPC' do
+    stub_rpc('eth_chainId' => '0x1', 'eth_blockNumber' => '0x123', 'eth_syncing' => false)
+    expect(described_class.chain_status(rpc_opts)).to include(chain_id: 1, block_number: 291, syncing: false)
+  end
+
+  it 'validates dynamic ABI string bounds and padding' do
+    words = [32, 3].map { |value| value.to_s(16).rjust(64, '0') }.join
+    dynamic = "0x#{words}#{'TOK'.unpack1('H*').ljust(64, '0')}"
+    stub_rpc('eth_getBlockByNumber' => { number: '0x1', hash: tx_hash }, 'eth_call' => dynamic)
+    expect(described_class.token_metadata(rpc_opts.merge(contract: address))).to include(name: 'TOK', symbol: 'TOK', decimals: nil)
+    stub_rpc('eth_getBlockByNumber' => { number: '0x1', hash: tx_hash }, 'eth_call' => "#{dynamic[0...-1]}1")
+    expect(described_class.token_metadata(rpc_opts.merge(contract: address))[:unavailable]).to include(:name, :symbol)
+  end
+
+  it 'rejects transport redirects, TLS failures and missing results without revealing endpoints' do
+    [RestClient::MovedPermanently.new, OpenSSL::SSL::SSLError.new('secret endpoint')].each do |error|
+      allow(RestClient::Request).to receive(:execute).and_raise(error)
+      expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, 'Ethereum HTTP transport failed') { |failure| expect(failure.cause).to be_nil }
+    end
+    allow(RestClient::Request).to receive(:execute).and_return(double(body: '{"jsonrpc":"2.0","id":1}'))
+    expect { described_class.chain_status(rpc_opts) }.to raise_error(described_class::RPCError, 'Missing JSON-RPC result')
+  end
+
+  it 'validates numeric boundaries and filters before issuing requests' do
+    expect(RestClient::Request).not_to receive(:execute)
+    expect { described_class.chain_status(rpc_opts.merge(timeout: 0)) }.to raise_error(ArgumentError)
+    expect { described_class.block(rpc_opts.merge(block: '0x01')) }.to raise_error(ArgumentError)
+    expect { described_class.event_logs(rpc_opts.merge(from_block: 2, to_block: 1)) }.to raise_error(ArgumentError)
+    expect { described_class.event_logs(rpc_opts.merge(from_block: 1, to_block: 1, topics: ['0x1'])) }.to raise_error(ArgumentError)
+    expect { described_class.address_activity(rpc_opts.merge(address: address, from_block: 1, to_block: 2, page_size: 101)) }.to raise_error(ArgumentError)
+  end
+
+  it 'includes every public API in usable help' do
+    expect { described_class.help }.to output(/token_metadata.*get_latest_block/m).to_stdout
+  end
+
   it 'should display information for authors' do
     authors_response = PWN::Blockchain::ETH
     expect(authors_response).to respond_to :authors

data/spec/lib/pwn/blockchain_spec.rb

@@ -7,4 +7,10 @@ describe PWN::Blockchain do
     help_response = PWN::Blockchain.help
     expect(help_response).not_to be_nil
   end
+
+  it 'lists the read-only intelligence modules and their detailed help entry points' do
+    result = nil
+    expect { result = described_class.help }.to output(/BTC.help.*ETH.help/m).to_stdout
+    expect(result).to include(:BTC, :ETH)
+  end
 end

data/spec/lib/pwn/config_spec.rb

@@ -23,6 +23,16 @@ describe PWN::Config do
     expect(env[:ai_profiles][:local]).to eq(model: 'fixture')
   end
 
+  it 'defaults every TUI role to the configured palette' do
+    expect(described_class.env_template.dig(:ai, :tui, :theme)).to eq(
+      border: 'black', title: 'red', operator: 'red', request: 'white',
+      assistant: 'white', task: 'green', tool: 'cyan', result: 'yellow',
+      notice: 'cyan', warning: 'red', category: 'yellow', value: 'white',
+      composer: 'white', header: 'white', footer: 'white', prompt: 'red',
+      selection: 'red', status: 'yellow'
+    )
+  end
+
   describe '.env_template AI providers' do
     let(:ai) { described_class.env_template[:ai] }