Module: PWN::Blockchain::ETH

Defined in:
lib/pwn/blockchain/eth.rb

Overview

Read-only Ethereum intelligence via BlockCypher and explicit JSON-RPC endpoints.

Defined Under Namespace

Classes: RPCError

Constant Summary collapse

TRANSFER_TOPIC = 
'0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

Class Method Summary collapse

Class Method Details

.account(opts = {}) ⇒ Object

Inspect balance, nonce and bytecode at one pinned block hash.

Supported Method Parameters

PWN::Blockchain::ETH.account( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', address: 'required - 0x-prefixed 20-byte account address', block: 'optional - block number, hash or stable tag, default latest', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )



271
272
273
274
275
276
277
278
279
 
# File 'lib/pwn/blockchain/eth.rb', line 271

public_class_method def self.(opts = {})
  address = hex_identifier(value: opts[:address], size: 20)
  context = snapshot(opts)
  params = [address, { blockHash: context[:block_hash], requireCanonical: true }]
  context.merge(source: :ethereum_json_rpc, address: address,
                balance_wei: quantity(value: rpc(opts.merge(method: 'eth_getBalance', params: params))),
                nonce: quantity(value: rpc(opts.merge(method: 'eth_getTransactionCount', params: params))),
                code: hex_data(value: rpc(opts.merge(method: 'eth_getCode', params: params))))
end

.address_activity(opts = {}) ⇒ Object

Scan top-level transactions in bounded whole-block pages, not internal calls or token events.

Supported Method Parameters

PWN::Blockchain::ETH.address_activity( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', address: 'required - 0x-prefixed 20-byte account address', from_block: 'required - nonnegative integer page start height', to_block: 'required - integer inclusive end height', page_size: 'optional - blocks to scan from 1 to 100, default 10; resume with next_block', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )

Raises:

  • (ArgumentError) 


108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/pwn/blockchain/eth.rb', line 108

public_class_method def self.address_activity(opts = {})
  address = hex_identifier(value: opts[:address], size: 20)
  first, last = numeric_range(opts)
  size = opts.fetch(:page_size, 10)
  raise ArgumentError, 'page_size must be an integer from 1 to 100' unless size.is_a?(Integer) && size.between?(1, 100)

  stop = [first + size - 1, last].min
  blocks = []
  transactions = []
  (first..stop).each do |height|
    data = block(opts.merge(block: height, full_transactions: true))[:block]
    raise RPCError, 'Missing or inconsistent activity block' unless data && quantity(value: data[:number]) == height && data[:transactions].is_a?(Array)

    hash = hex_identifier(value: data[:hash], size: 32)
    blocks << { number: height, hash: hash }
    data[:transactions].each do |tx|
      raise RPCError, 'Expected full transaction object' unless tx.is_a?(Hash)

      next unless [tx[:from], tx[:to]].compact.any? { |value| value.is_a?(String) && value.downcase == address }

      transactions << tx.merge(block_number: height, block_hash: hash, value_wei: quantity(value: tx[:value]))
    end
  end
  { source: :ethereum_json_rpc, address: address, transactions: transactions, blocks: blocks,
    next_block: stop < last ? stop + 1 : nil, complete: stop == last,
    coverage: :top_level_transactions_only, internal_traces: :not_covered,
    token_events: :not_covered, reorg_safe: false, from_block: first, to_block: stop }
end

.authors ⇒ Object

Author(s)

0day Inc. [email protected]



418
419
420
421
422
 
# File 'lib/pwn/blockchain/eth.rb', line 418

public_class_method def self.authors
  "AUTHOR(S):
    0day Inc. <[email protected]>
  "
end

.block(opts = {}) ⇒ Object

Read a block by number, tag or hash; raw quantities remain exact hex.

Supported Method Parameters

PWN::Blockchain::ETH.block( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', block: 'optional - nonnegative integer, canonical hex quantity, tag or 32-byte hash; default latest', full_transactions: 'optional - boolean to return transaction objects, default false', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )

Raises:

  • (ArgumentError) 


235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/pwn/blockchain/eth.rb', line 235

public_class_method def self.block(opts = {})
  selector = opts.key?(:block) ? opts[:block] : 'latest'
  full = opts.fetch(:full_transactions, false)
  raise ArgumentError, 'full_transactions must be boolean' unless [true, false].include?(full)

  by_hash = selector.is_a?(String) && selector.match?(/\A0x[0-9a-fA-F]{64}\z/)
  selector = by_hash ? hex_identifier(value: selector, size: 32) : block_tag(value: selector)
  result = rpc(opts.merge(method: by_hash ? 'eth_getBlockByHash' : 'eth_getBlockByNumber', params: [selector, full]))
  raise RPCError, 'Invalid block response' unless result.nil? || result.is_a?(Hash)

  if result && selector != 'pending'
    hash = hex_identifier(value: result[:hash], size: 32)
    number = quantity(value: result[:number])
    raise RPCError, 'Block hash does not match request' if by_hash && hash != selector
    raise RPCError, 'Block height does not match request' if !by_hash && selector.start_with?('0x') && number != quantity(value: selector)
  end
  { source: :ethereum_json_rpc, requested_block: selector, block: result }
end

.call(opts = {}) ⇒ Object

Execute read-only eth_call at a pinned canonical block; no signing or submission.

Supported Method Parameters

PWN::Blockchain::ETH.call( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', contract: 'required - 0x-prefixed 20-byte contract address', data: 'required - ABI-encoded even-length 0x-prefixed calldata, maximum 128 KiB', block: 'optional - block number, hash or stable tag, default latest', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )

Raises:

  • (ArgumentError) 


146
147
148
149
150
151
152
153
154
155
 
# File 'lib/pwn/blockchain/eth.rb', line 146

public_class_method def self.call(opts = {})
  address = hex_identifier(value: opts[:contract], size: 20)
  data = hex_data(value: opts[:data])
  raise ArgumentError, 'Calldata exceeds 128 KiB' if data.length > 262_146

  context = snapshot(opts)
  params = [{ to: address, data: data }, { blockHash: context[:block_hash], requireCanonical: true }]
  result = hex_data(value: rpc(opts.merge(method: 'eth_call', params: params)))
  context.merge(source: :ethereum_json_rpc, contract: address, data: result)
end

.chain_status(opts = {}) ⇒ Object

Read the endpoint chain identity, head height and sync state.

Supported Method Parameters

PWN::Blockchain::ETH.chain_status( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )



357
358
359
360
361
362
363
364
365
366
 
# File 'lib/pwn/blockchain/eth.rb', line 357

public_class_method def self.chain_status(opts = {})
  rpc_url = opts[:rpc_url]
  context = opts.merge(rpc_url: rpc_url)
  {
    source: :ethereum_json_rpc,
    chain_id: quantity(value: rpc(context.merge(method: 'eth_chainId'))),
    block_number: quantity(value: rpc(context.merge(method: 'eth_blockNumber'))),
    syncing: rpc(context.merge(method: 'eth_syncing'))
  }
end

.decode_transfer(opts = {}) ⇒ Object

Decode the standard Transfer event layout, not contract conformance.

Supported Method Parameters

PWN::Blockchain::ETH.decode_transfer( log: 'required - symbol-keyed log with topics and data; unknown signatures return nil' )

Raises:

  • (ArgumentError) 


21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/pwn/blockchain/eth.rb', line 21

public_class_method def self.decode_transfer(opts = {})
  log = opts[:log]
  raise ArgumentError, 'log must be a hash with topics' unless log.is_a?(Hash) && log[:topics].is_a?(Array)

  topics = log[:topics]
  raise ArgumentError, 'Too many event topics' if topics.length > 4

  topics.each { |topic| hex_identifier(value: topic, size: 32) }
  return nil unless topics.first.is_a?(String) && topics.first.downcase == TRANSFER_TOPIC

  raise ArgumentError, 'Invalid Transfer topic count' unless [3, 4].include?(topics.length)

  raise ArgumentError, 'Noncanonical indexed address' unless topics[1..2].all? { |topic| topic.match?(/\A0x0{24}[0-9a-fA-F]{40}\z/) }

  result = { standard: topics.length == 3 ? :erc20 : :erc721, conformance: :unverified,
             from: "0x#{topics[1][-40..].downcase}", to: "0x#{topics[2][-40..].downcase}" }
  if topics.length == 3
    result[:value] = hex_identifier(value: log[:data], size: 32).to_i(16)
  else
    raise ArgumentError, 'ERC721 Transfer data must be empty' unless log[:data] == '0x'

    result[:token_id] = topics[3].to_i(16)
  end
  result
end

.event_logs(opts = {}) ⇒ Object

Query bounded logs; provider truncation cannot be independently detected.

Supported Method Parameters

PWN::Blockchain::ETH.event_logs( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', from_block: 'required - nonnegative integer start height', to_block: 'required - integer inclusive end height; maximum span 1000 blocks', address: 'optional - 20-byte emitting contract address filter', topics: 'optional - up to four 32-byte topic filters or nil wildcards', limit: 'optional - returned log cap from 1 to 10000, default 1000', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )

Raises:

  • (ArgumentError) 


66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/pwn/blockchain/eth.rb', line 66

public_class_method def self.event_logs(opts = {})
  first, last = numeric_range(opts)
  raise ArgumentError, 'Log range exceeds 1000 blocks' if last - first >= 1000

  limit = opts.fetch(:limit, 1000)
  raise ArgumentError, 'limit must be an integer from 1 to 10000' unless limit.is_a?(Integer) && limit.between?(1, 10_000)

  filter = { fromBlock: block_tag(value: first), toBlock: block_tag(value: last) }
  filter[:address] = hex_identifier(value: opts[:address], size: 20) if opts[:address]
  topics = opts.fetch(:topics, [])
  raise ArgumentError, 'topics must be an array of at most four topics' unless topics.is_a?(Array) && topics.length <= 4

  filter[:topics] = topics.map { |topic| topic.nil? ? nil : hex_identifier(value: topic, size: 32) }
  logs = rpc(opts.merge(method: 'eth_getLogs', params: [filter]))
  raise RPCError, 'Invalid logs response' unless logs.is_a?(Array)

  rows = logs.first(limit).map do |log|
    raise RPCError, 'Invalid log object' unless log.is_a?(Hash)

    hex_identifier(value: log[:address], size: 20)
    hex_data(value: log[:data])
    height = quantity(value: log[:blockNumber])
    raise RPCError, 'Provider log outside requested range' unless height.between?(first, last)

    hex_identifier(value: log[:transactionHash], size: 32)
    log.merge(transfer: decode_transfer(log: log))
  end
  { source: :ethereum_json_rpc, from_block: first, to_block: last, logs: rows,
    truncated: logs.length > limit, complete: false, provider_completeness: :unverified,
    returned_count: rows.length, internal_traces: :not_covered }
end

.get_block_details(opts = {}) ⇒ Object

Supported Method Parameters

PWN::Blockchain::ETH.get_block_details( height: 'required - block height number', token: 'optional - API token for higher rate limits' )



401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/pwn/blockchain/eth.rb', line 401

public_class_method def self.get_block_details(opts = {})
  height = opts[:height]
  raise ArgumentError, 'height must be a nonnegative integer or decimal string' unless (height.is_a?(Integer) && height >= 0) || (height.is_a?(String) && height.match?(/\A(?:0|[1-9][0-9]*)\z/))

  params = {}
  params[:token] = opts[:token] if opts[:token]

  rest_call = "main/blocks/#{height}"
  response = eth_rest_call(rest_call: rest_call, params: params)

  JSON.parse(response.body, symbolize_names: true)
rescue JSON::ParserError
  raise RPCError, 'Invalid BlockCypher JSON response', cause: nil
end

.get_latest_block(opts = {}) ⇒ Object

Supported Method Parameters

latest_block = PWN::Blockchain::ETH.get_latest_block( token: 'optional - API token for higher rate limits' )



384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/pwn/blockchain/eth.rb', line 384

public_class_method def self.get_latest_block(opts = {})
  params = {}
  params[:token] = opts[:token] if opts[:token]

  rest_call = 'main'
  response = eth_rest_call(rest_call: rest_call, params: params)

  JSON.parse(response.body, symbolize_names: true)
rescue JSON::ParserError
  raise RPCError, 'Invalid BlockCypher JSON response', cause: nil
end

.help ⇒ Object

Display Usage for this Module



426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/pwn/blockchain/eth.rb', line 426

public_class_method def self.help
  puts "USAGE:
    # Read endpoint chain identity, height and synchronization state.
    #{self}.chain_status(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint; never persisted',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Read a block with raw exact hex quantities.
    #{self}.block(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint',
      block: 'optional - integer, canonical hex quantity, tag or 32-byte hash; default latest',
      full_transactions: 'optional - boolean transaction object expansion, default false',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Inspect receipt status and exact execution/blob fees, excluding L2 surcharges.
    #{self}.transaction(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint',
      hash: 'required - 0x-prefixed 32-byte transaction hash',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Inspect balance, nonce and code using EIP-1898 pinned canonical block reads.
    #{self}.account(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint supporting EIP-1898',
      address: 'required - 0x-prefixed 20-byte account address',
      block: 'optional - integer, canonical hex, hash or stable tag; default latest',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Query bounded event logs; silent provider truncation remains unverified.
    #{self}.event_logs(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint',
      from_block: 'required - nonnegative integer start height',
      to_block: 'required - inclusive integer end height; maximum 1000 blocks',
      address: 'optional - 0x-prefixed 20-byte emitting contract address',
      topics: 'optional - array of at most four 32-byte topics or nil wildcards',
      limit: 'optional - result cap from 1 to 10000, default 1000; truncation is explicit',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Decode standard ERC20/ERC721 Transfer layouts, not ERC1155 or proven conformance.
    #{self}.decode_transfer(
      log: 'required - symbol-keyed log with topics and data; unknown signatures return nil'
    )

    # Scan whole-block pages of top-level transactions; no token events or internal traces.
    #{self}.address_activity(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint',
      address: 'required - 0x-prefixed 20-byte account address',
      from_block: 'required - nonnegative integer page start; resume with next_block',
      to_block: 'required - inclusive integer end height',
      page_size: 'optional - blocks per page from 1 to 100, default 10',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Execute ABI-encoded read-only eth_call at a pinned block, never send or sign.
    #{self}.call(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint supporting EIP-1898',
      contract: 'required - 0x-prefixed 20-byte contract address',
      data: 'required - even-length 0x-prefixed ABI calldata, maximum 128 KiB',
      block: 'optional - integer, canonical hex, hash or stable tag; default latest',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Read token metadata at one block; empty/malformed ABI fields are unavailable, RPC errors propagate.
    #{self}.token_metadata(
      rpc_url: 'required - explicit HTTP(S) JSON-RPC endpoint supporting EIP-1898',
      contract: 'required - 0x-prefixed 20-byte token contract address',
      block: 'optional - integer, canonical hex, hash or stable tag; default latest',
      timeout: 'optional - request timeout from 1 to 120 seconds, default 30'
    )

    # Coverage excludes internal traces. Activity completeness is only for the requested
    # top-level range; block pages can reorganize. Use finalized ranges where possible.
    # RPC errors are redacted. No implicit endpoint, keys, signing or wallet changes.

    # Run get latest block and return its result
    #{self}.get_latest_block(
      token: 'optional - API token for higher rate limits'
    )

    # Run get block details and return its result
    #{self}.get_block_details(
      height: 'required - block height number',
      token: 'optional - API token for higher rate limits'
    )

    # Print the AUTHOR(S) string for this module.
    #{self}.authors
  "
  constants.sort
end

.token_metadata(opts = {}) ⇒ Object

Read optional token metadata; layouts do not prove ERC conformance, and RPC failures propagate.

Supported Method Parameters

PWN::Blockchain::ETH.token_metadata( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint supporting EIP-1898', contract: 'required - 0x-prefixed 20-byte token contract address', block: 'optional - integer, hash or stable tag for pinned reads, default latest', timeout: 'optional - request timeout from 1 to 120 seconds, default 30' )



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/pwn/blockchain/eth.rb', line 165

public_class_method def self.token_metadata(opts = {})
  contract = hex_identifier(value: opts[:contract], size: 20)
  context = snapshot(opts)
  result = context.merge(source: :ethereum_json_rpc, contract: contract, conformance: :unverified, unavailable: [])
  { name: '0x06fdde03', symbol: '0x95d89b41', decimals: '0x313ce567', total_supply: '0x18160ddd' }.each do |field, selector|
    params = [{ to: contract, data: selector }, { blockHash: context[:block_hash], requireCanonical: true }]
    raw = hex_data(value: rpc(opts.merge(method: 'eth_call', params: params)))
    value = if %i[name symbol].include?(field)
              abi_string(value: raw)
            elsif raw.match?(/\A0x[0-9a-fA-F]{64}\z/)
              raw.to_i(16)
            end
    value = nil if field == :decimals && value && value > 255
    result[field] = value
    result[:unavailable] << field if value.nil?
  end
  result
end

.transaction(opts = {}) ⇒ Object

Inspect transaction and receipt; fees exclude chain-specific L2 surcharges.

Supported Method Parameters

PWN::Blockchain::ETH.transaction( rpc_url: 'required - explicit Ethereum HTTP(S) JSON-RPC endpoint', hash: 'required - 0x-prefixed 32-byte transaction hash', timeout: 'optional - request timeout in seconds from 1 to 120, default 30' )

Raises:



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/pwn/blockchain/eth.rb', line 288

public_class_method def self.transaction(opts = {})
  hash = hex_identifier(value: opts[:hash], size: 32)
  tx = rpc(opts.merge(method: 'eth_getTransactionByHash', params: [hash]))
  result = { source: :ethereum_json_rpc, hash: hash, internal_traces: :not_covered }
  return result.merge(status: :not_found) if tx.nil?

  raise RPCError, 'Invalid transaction response' unless tx.is_a?(Hash) && tx[:hash]&.downcase == hash

  receipt = rpc(opts.merge(method: 'eth_getTransactionReceipt', params: [hash]))
  result.merge!(transaction: tx, receipt: receipt, value_wei: quantity(value: tx[:value]), block_number: tx[:blockNumber] && quantity(value: tx[:blockNumber]))
  return result.merge(status: tx[:blockNumber] ? :receipt_unavailable : :pending) unless receipt

  raise RPCError, 'Invalid receipt response' unless receipt.is_a?(Hash) && receipt[:transactionHash]&.downcase == hash

  raise RPCError, 'Transaction and receipt inclusion heights differ' if receipt[:blockNumber] && receipt[:blockNumber] != tx[:blockNumber]
  raise RPCError, 'Transaction and receipt block hashes differ' if receipt[:blockHash] && tx[:blockHash] && receipt[:blockHash].downcase != tx[:blockHash].downcase

  status = receipt[:status] && quantity(value: receipt[:status])
  raise RPCError, 'Invalid receipt status' unless [nil, 0, 1].include?(status)

  gas_price = receipt[:effectiveGasPrice] || tx[:gasPrice]
  fee = gas_price && (quantity(value: receipt[:gasUsed]) * quantity(value: gas_price))
  blob_fee = (quantity(value: receipt[:blobGasUsed]) * quantity(value: receipt[:blobGasPrice]) if receipt[:blobGasUsed] && receipt[:blobGasPrice])
  result.merge(status: { 0 => :reverted, 1 => :success }.fetch(status, :unknown),
               block_hash: receipt[:blockHash], execution_fee_wei: fee, blob_fee_wei: blob_fee,
               fee_scope: :execution_and_blob_only, contract_creation: tx[:to].nil?, contract_address: receipt[:contractAddress])
end