eth 0.4.12 → 0.5.0

data/README.md

@@ -1,145 +1,221 @@
-# Eth [![Travis-CI](https://travis-ci.org/se3000/ruby-eth.svg?branch=master)](https://travis-ci.org/se3000/ruby-eth) [![Code Climate](https://codeclimate.com/github/se3000/ruby-eth/badges/gpa.svg)](https://codeclimate.com/github/se3000/ruby-eth) [![Gitter](https://badges.gitter.im/ruby-eth/Lobby.svg)](https://gitter.im/ruby-eth/Lobby)
-
-A simple library to build and sign Ethereum transactions. Allows separation of key and node management. Sign transactions and handle keys anywhere you can run ruby, broadcast transactions through any node.
-
-## Installation
+# Eth for Ruby
+
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/q9f/eth.rb/Spec)](https://github.com/q9f/eth.rb/actions)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/q9f/eth.rb)](https://github.com/q9f/eth.rb/releases)
+[![Gem](https://img.shields.io/gem/v/eth)](https://rubygems.org/gems/eth)
+[![Gem](https://img.shields.io/gem/dt/eth)](https://rubygems.org/gems/eth)
+[![codecov](https://codecov.io/gh/q9f/eth.rb/branch/main/graph/badge.svg?token=IK7USBPBZY)](https://codecov.io/gh/q9f/eth.rb)
+[![Maintainability](https://api.codeclimate.com/v1/badges/469e6f66425198ad7614/maintainability)](https://codeclimate.com/github/q9f/eth.rb/maintainability)
+[![Yard Doc API](https://img.shields.io/badge/docs-API-blue)](https://q9f.github.io/eth.rb)
+[![GitHub top language](https://img.shields.io/github/languages/top/q9f/eth.rb?color=red)](https://github.com/q9f/eth.rb/pulse)
+[![GitHub](https://img.shields.io/github/license/q9f/eth.rb)](LICENSE)
+
+A simple library to build and sign Ethereum transactions. Allows separation of key and node management. Sign transactions and handle keys anywhere you can run ruby, broadcast transactions through any node. Sign messages and recover signatures for authentication.
+
+What you get:
+- [x] Secp256k1 Key-Pairs and Encrypted Ethereum Key-Stores (JSON)
+- [x] EIP-55 Checksummed Ethereum Addresses
+- [x] EIP-155 Replay protection with Chain IDs (with presets)
+- [x] EIP-191 Ethereum Signed Messages (with prefix and type)
+- [x] EIP-712 Ethereum Signed Type Data
+- [x] EIP-1559 Ethereum Type-2 Transactions (with priority fee and max gas fee)
+- [x] EIP-2028 Call-data intrinsic gas cost estimates (plus access lists)
+- [x] EIP-2718 Ethereum Transaction Envelopes (and types)
+- [x] EIP-2930 Ethereum Type-1 Transactions (with access lists)
+- [x] ABI-Encoder and Decoder (including type parser)
+
+Soon (TM):
+- [ ] RLP-Encoder and Decoder (including sedes)
+- [ ] RPC-Client (HTTP) for Execution APIs and Consensus APIs
+- [ ] Smart Contracts and Solidity Support
+- [ ] EIP-1271 Smart-Contract Authentification
+- [ ] HD-Wallets (BIP-32) and Mnemonics (BIP-39)
+
+Contents:
+- [1. Installation](#1-installation)
+- [2. Usage](#2-usage)
+  - [2.1. Ethereum Keys and Addresses (EIP-55)](#21-ethereum-keys-and-addresses-eip-55)
+  - [2.2. Ethereum Signatures (EIP-191, EIP-712)](#22-ethereum-signatures-eip-191-eip-712)
+  - [2.3. Ethereum Chains (EIP-155)](#23-ethereum-chains-eip-155)
+  - [2.4. Ethereum Transactions (EIP-1559, EIP-2718, EIP-2930)](#24-ethereum-transactions-eip-1559-eip-2718-eip-2930)
+  - [2.5. Ethereum ABI Encoder and Decoder](#25-ethereum-abi-encoder-and-decoder)
+- [3. Documentation](#3-documentation)
+- [4. Testing](#4-testing)
+- [5. Contributing](#5-contributing)
+- [6. License and Credits](#6-license-and-credits)
+
+## 1. Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'eth'
+gem "eth"
 ```
 
-And then execute:
-
-    $ bundle
-
 Or install it yourself as:
 
-    $ gem install eth
+```shell
+gem install eth
+```
 
-## Usage
+## 2. Usage
 
-### Keys
+### 2.1. Ethereum Keys and Addresses (EIP-55)
 
-Create a new public/private key and get its address:
+Generate a random Secp256k1 key-pair.
 
 ```ruby
 key = Eth::Key.new
-key.private_hex
-key.public_hex
-key.address # EIP55 checksummed address
+# => #<Eth::Key:0x00005574a6ba80b8 @private_key=#<Secp256k1::PrivateKey:0x00005574a6b9a0a8 @data=")&\x86P\xB5\x16\xD9]\xFA;\x1F\xF6\xD9\xCF\xE3Vj/\xE2\x81\xC0\x9D\xE9\x05o!q\x82G\x9A\x10Q">, @public_key=#<Secp256k1::PublicKey:0x00005574a6b9bf98>>
 ```
 
-Import an existing key:
+Create an password-encrypted Ethereum key-store.
 
 ```ruby
-old_key = Eth::Key.new priv: private_key
+my_key = Eth::Key.new priv: "30137644b564785d01420f8043f043d74dcca64008e57c59f8ce713a0005a54b"
+key_store = Eth::Key::Encrypter.perform my_key, "secret-password-1337"
+# => "{\"crypto\":{\"cipher\":\"aes-128-ctr\",\"cipherparams\":{\"iv\":\"7e5c0fe1e27f4ea61b0f4427dd63555f\"},\"ciphertext\":\"6353653bba494cdae6bcd510febc980cdc6f7b23cfbdf950d7a909a69625c8fd\",\"kdf\":\"pbkdf2\",\"kdfparams\":{\"c\":262144,\"dklen\":32,\"prf\":\"hmac-sha256\",\"salt\":\"cce96286f3c32267fc91f756365307fe6a4c83b6b2a73c69535f721fa407736c\"},\"mac\":\"3361ffd2b158a1d7bca5a5fd86a251ba3e9d80b602c867a2e0f47023a0e17a57\"},\"id\":\"642ee9fc-72e4-4d0a-902f-247c0b59bfda\",\"version\":3}"
+restored_key = Eth::Key::Decrypter.perform key_store, "secret-password-1337"
+# => "30137644b564785d01420f8043f043d74dcca64008e57c59f8ce713a0005a54b"
 ```
 
-Or decrypt an [encrypted key](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition):
+Manage Ethereum address objects adhering to EIP-55 checksum format.
 
 ```ruby
-decrypted_key = Eth::Key.decrypt File.read('./some/path.json'), 'p455w0rD'
+address = Eth::Address.new "0xd496b23d61f88a8c7758fca7560dcfac7b3b01f9"
+# => #<Eth::Address:0x00005574a6bd4fc8 @address="0xd496b23d61f88a8c7758fca7560dcfac7b3b01f9">
+address.valid?
+# => true
+address.checksummed # EIP 55
+# => "0xD496b23D61F88A8C7758fca7560dCFac7b3b01F9"
 ```
 
-You can also encrypt your keys for use with other ethereum libraries:
+See `/spec` or [Documentation](https://q9f.github.io/eth.rb/) for more details about key-pairs, encrypting/decrypting key-stores with a secret, and checksummed addresses.
 
-```ruby
-encrypted_key_info = Eth::Key.encrypt key, 'p455w0rD'
-```
-
-### Transactions
-
-Build a transaction from scratch:
-
-```ruby
-tx = Eth::Tx.new({
-  data: hex_data,
-  gas_limit: 21_000,
-  gas_price: 3_141_592,
-  nonce: 1,
-  to: key2.address,
-  value: 1_000_000_000_000,
-})
-```
+### 2.2. Ethereum Signatures (EIP-191, EIP-712)
 
-Or decode an encoded raw transaction:
+Manage keypairs to sign messages in EIP-191 (`personal_sign`) format or typed data in EIP-712 (`sign_typed_data`) format.
 
 ```ruby
-tx = Eth::Tx.decode hex
+key = Eth::Key.new priv: "268be6f4a68c40f6862b7ac9aed8f701dc25a95ddb9a44d8b1f520b75f440a9a"
+# => #<Eth::Key:0x00005574a699adc0 @private_key=#<Secp256k1::PrivateKey:0x00005574a6998200 @data="&\x8B\xE6\xF4\xA6\x8C@\xF6\x86+z\xC9\xAE\xD8\xF7\x01\xDC%\xA9]\xDB\x9AD\xD8\xB1\xF5 \xB7_D\n\x9A">, @public_key=#<Secp256k1::PublicKey:0x00005574a6998160>>
+key.public_hex
+# => "04b45200621c013a5fbab999ac33b0c836328a04afa0255ffbe6ea0f6fd97e187b02199886d942a9f50f7e279a2bc74c93b2afcbd7255489939f9b36a5eae5e281"
+key.address.to_s
+# => "0xD496b23D61F88A8C7758fca7560dCFac7b3b01F9"
+key.personal_sign "Hello World!"
+# => "ac6a59417d8688c8144f01a662384fa691636b48a071d4b7c13902bb87ca472b0bce1d7a758f39a5759ed5e937ce61f50dd1b83158371f8d0faeb9b7d81c194225"
 ```
 
-Then sign the transaction:
+Recover and verify personal signatures respecting EIPs 155, 191, and 712.
 
 ```ruby
-tx.sign key
+address = Eth::Address.new "0xd496b23d61f88a8c7758fca7560dcfac7b3b01f9"
+# => #<Eth::Address:0x00005574a6bd4fc8 @address="0xd496b23d61f88a8c7758fca7560dcfac7b3b01f9">
+signature = "ac6a59417d8688c8144f01a662384fa691636b48a071d4b7c13902bb87ca472b0bce1d7a758f39a5759ed5e937ce61f50dd1b83158371f8d0faeb9b7d81c19422d"
+# => "ac6a59417d8688c8144f01a662384fa691636b48a071d4b7c13902bb87ca472b0bce1d7a758f39a5759ed5e937ce61f50dd1b83158371f8d0faeb9b7d81c19422d"
+recovered_key = Eth::Signature.personal_recover "Hello World!", signature, Eth::Chain::GOERLI
+# => "04b45200621c013a5fbab999ac33b0c836328a04afa0255ffbe6ea0f6fd97e187b02199886d942a9f50f7e279a2bc74c93b2afcbd7255489939f9b36a5eae5e281"
+Eth::Util.public_key_to_address(recovered_key).to_s
+# => "0xD496b23D61F88A8C7758fca7560dCFac7b3b01F9"
+Eth::Signature.verify "Hello World!", signature, address, Eth::Chain::GOERLI
+# => true
 ```
 
-Get the raw transaction with `tx.hex`, and broadcast it through any Ethereum node. Or, just get the TXID with `tx.hash`.
+See `/spec` or [Documentation](https://q9f.github.io/eth.rb/) for signing typed data as per EIP-712.
 
-### Utils
+### 2.3. Ethereum Chains (EIP-155)
 
-Validate an [EIP55](https://github.com/ethereum/EIPs/issues/55) checksummed address:
+Manage Ethereum chain IDs for EIP-155 replay protection.
 
 ```ruby
-Eth::Utils.valid_address? address
+chain_id = Eth::Chain::OPTIMISM
+# => 10
+v = Eth::Chain.to_v 0, Eth::Chain::OPTIMISM
+# => 55
+recovery_id = Eth::Chain.to_recovery_id v, Eth::Chain::OPTIMISM
+# => 0
+chain_id = Eth::Chain.to_chain_id v
+# => 10
 ```
 
-Or add a checksum to an existing address:
+### 2.4. Ethereum Transactions (EIP-1559, EIP-2718, EIP-2930)
 
-```ruby
-Eth::Utils.format_address "0x4bc787699093f11316e819b5692be04a712c4e69" # => "0x4bc787699093f11316e819B5692be04A712C4E69"
-```
-
-### Personal Signatures
-
-You can recover public keys and generate web3/metamask-compatible signatures:
+Create an EIP-1559-conform transaction:
 
 ```ruby
-# Generate signature
-key.personal_sign('hello world')
-
-# Recover signature
-message = 'test'
-signature = '0x3eb24bd327df8c2b614c3f652ec86efe13aa721daf203820241c44861a26d37f2bffc6e03e68fc4c3d8d967054c9cb230ed34339b12ef89d512b42ae5bf8c2ae1c'
-Eth::Key.personal_recover(message, signature) # => 043e5b33f0080491e21f9f5f7566de59a08faabf53edbc3c32aaacc438552b25fdde531f8d1053ced090e9879cbf2b0d1c054e4b25941dab9254d2070f39418afc
+payload = {
+  chain_id: Eth::Chain::GOERLI,
+  nonce: 5,
+  priority_fee: 3 * Eth::Unit::GWEI,
+  max_gas_fee: 69 * Eth::Unit::GWEI,
+  gas_limit: 230_420,
+  to: "0xCaA29806044A08E533963b2e573C1230A2cd9a2d",
+  value: 0.069423 * Eth::Unit::ETHER,
+}
+# => {:chain_id=>5, :nonce=>5, :priority_fee=>0.3e10, :max_gas_fee=>0.69e11, :gas_limit=>230420, :to=>"0xCaA29806044A08E533963b2e573C1230A2cd9a2d", :value=>0.69423e17}
+tx = Eth::Tx.new payload
+# => #<Eth::Tx::Eip1559:0x0000557e35fc5a68 @access_list=[], @amount=69423000000000000, @chain_id=5, @destination="CaA29806044A08E533963b2e573C1230A2cd9a2d", @gas_limit=230420, @max_fee_per_gas=69000000000, @max_priority_fee_per_gas=3000000000, @payload="", @sender="", @signature_r=0, @signature_s=0, @signature_y_parity=nil, @signer_nonce=5, @type=2>
+my_key = Eth::Key.new priv: "30137644b564785d01420f8043f043d74dcca64008e57c59f8ce713a0005a54b"
+# => #<Eth::Key:0x0000557e36243178 @private_key=#<Secp256k1::PrivateKey:0x0000557e36242d40 @data="0\x13vD\xB5dx]\x01B\x0F\x80C\xF0C\xD7M\xCC\xA6@\b\xE5|Y\xF8\xCEq:\x00\x05\xA5K">, @public_key=#<Secp256k1::PublicKey:0x0000557e36242cf0>>
+tx.sign my_key
+# => "cba302c0ebf8d0205a78ae97f560419b407e32e2426f416abc95a9bfc9dac09c"
+tx.hex
+# => "02f873050584b2d05e00851010b872008303841494caa29806044a08e533963b2e573c1230a2cd9a2d87f6a3d9c63df00080c080a03aa187d10b138d3e0155729adb961cd89e10f988ba2d19d6869770b9e5a23d10a04d40864600136ae214916043c7d63b849c98db757e95c86983a036982816e1af"
 ```
 
-### Configure
+This gem also supports access lists and ABI-encoded data payloads. See `/spec` or [Documentation](https://q9f.github.io/eth.rb/) for more details about the various supported transaction types (legacy, type-1, type-2), payload parameters, and how to estimate intrinsic gas costs.
 
-In order to prevent replay attacks, you must specify which Ethereum chain your transactions are created for. See [EIP 155](https://github.com/ethereum/EIPs/issues/155) for more detail.
+### 2.5. Ethereum ABI Encoder and Decoder
+
+Encode and decode Ethereum application binary interface data (ABI).
 
 ```ruby
-Eth.configure do |config|
-  config.chain_id = 1 # nil by default, meaning valid on any chain
-end
+Eth::Util.bin_to_hex Eth::Abi.encode(["string", "address"], ["Hello, Bob!", "0xd496b23d61f88a8c7758fca7560dcfac7b3b01f9"])
+# => "0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000d496b23d61f88a8c7758fca7560dcfac7b3b01f9000000000000000000000000000000000000000000000000000000000000000b48656c6c6f2c20426f6221000000000000000000000000000000000000000000"
+Eth::Abi.decode(["string", "address"], "0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000d496b23d61f88a8c7758fca7560dcfac7b3b01f9000000000000000000000000000000000000000000000000000000000000000b48656c6c6f2c20426f6221000000000000000000000000000000000000000000")
+# => ["Hello, Bob!", "0xd496b23d61f88a8c7758fca7560dcfac7b3b01f9"]
 ```
 
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/se3000/ethereum-tx. Tests are encouraged.
+## 3. Documentation
 
-### Tests
+The documentation can be found at: https://q9f.github.io/eth.rb
 
-First install the [Ethereum common tests](https://github.com/ethereum/tests):
+For any specific version, docs can be generated by `yard`:
 
 ```shell
-git submodule update --init
+gem install bundler rdoc yard
+git checkout v0.5.0
+yard doc
 ```
 
-Then run the associated tests:
+The goal is to have 100% API documentation available.
+
+## 4. Testing
+
+To run tests, simply use `rspec`. Note, that the Ethereum tests fixtures are required.
 
 ```shell
+git submodule update --init --recursive
+bundle install
 rspec
 ```
 
-## License
+The goal is to have 100% specification coverage for all code inside this gem.
+
+## 5. Contributing
+
+Pull requests are welcome! To contribute, please consider the following:
+* Code should be fully documented. Run `yard doc` and make sure it does not yield any warnings or undocumented sets.
+* Code should be fully covered by tests. Run `rspec` to make sure all tests pass. The CI has an integration that will assis you to identify uncovered lines of code and get coverage up to 100%.
+* Code should be formatted properly. Try to eliminate the most common issues such as trailing white-spaces or duplicate new-lines. Usage of the `rufo` gem is recommended.
+* Submit pull requests, questions, or issues to Github: https://github.com/q9f/eth.rb
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+## 6. License and Credits
+The `eth` gem is licensed under the conditions of [Apache 2.0](./LICENSE.txt). Please see [AUTHORS](./AUTHORS.txt) for contributors and copyright notices.
 
-## TODO
+This gem is a complete rewrite of the old `eth` gem by Steve Ellis.
+* https://github.com/se3000/ruby-eth/ (MIT)
 
-* Better test suite.
-* Expose API for HD keys.
-* Support signing with [libsecp256k1](https://github.com/bitcoin-core/secp256k1).
+It also contains a revised version the ABI gem by Jan Xie and Zhang Yaning.
+* https://github.com/cryptape/ruby-ethereum-abi (MIT)

data/bin/console

@@ -1,10 +1,9 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "eth"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
+# use the local version of the code instead of a globally installed gem
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
 
+require "eth"
 require "pry"
+
 Pry.start

data/bin/setup

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
+
 set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
 bundle install
-
-# Do any other automated setup that you need to do here
+git submodule update --init --recursive
+yard doc
+rspec

data/eth.gemspec

@@ -1,31 +1,53 @@
+# frozen_string_literal: true
 # coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'eth/version'
+
+lib = File.expand_path("lib", __dir__).freeze
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include? lib
+
+require "eth/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "eth"
-  spec.version       = Eth::VERSION
-  spec.authors       = ["Steve Ellis"]
-  spec.email         = ["email@steveell.is"]
-
-  spec.summary       = %q{Simple API to sign Ethereum transactions.}
-  spec.description   = %q{Library to build, parse, and sign Ethereum transactions.}
-  spec.homepage      = "https://github.com/se3000/ruby-eth"
-  spec.license       = "MIT"
-
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.name = "eth"
+  spec.version = Eth::VERSION
+  spec.authors = ["Steve Ellis", "Afri Schoedon"]
+  spec.email = ["email@steveell.is", "ruby@q9f.cc"]
+
+  spec.summary = %q{Ruby Ethereum library.}
+  spec.description = %q{Library to handle Ethereum accounts, messages, and transactions.}
+  spec.homepage = "https://github.com/q9f/eth.rb"
+  spec.license = "Apache-2.0"
+
+  spec.metadata = {
+    "homepage_uri" => "https://github.com/q9f/eth.rb",
+    "source_code_uri" => "https://github.com/q9f/eth.rb",
+    "github_repo" => "https://github.com/q9f/eth.rb",
+    "bug_tracker_uri" => "https://github.com/q9f/eth.rb/issues",
+  }.freeze
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+  spec.test_files = spec.files.grep %r{^(test|spec|features)/}
+
+  spec.platform = Gem::Platform::RUBY
+  spec.required_ruby_version = ">= 2.6", "< 4.0"
+
+  # keccak for hashing everything in ethereum
+  spec.add_dependency "keccak", "~> 1.3"
+
+  # konstructor gem for overloading constructors
+  spec.add_dependency "konstructor", "~> 1.0"
+
+  # rbsecp256k1 for key-pairs and signatures
+  spec.add_dependency "rbsecp256k1", "~> 5.1"
+
+  # rlp for transaction encoding
+  spec.add_dependency "rlp", "~> 0.7"
 
-  spec.add_dependency 'digest-sha3-patched', '~> 1.1'
-  spec.add_dependency 'ffi', '~> 1.0'
-  spec.add_dependency 'money-tree', '~> 0.10.0'
-  spec.add_dependency 'rlp', '~> 0.7.3'
-  spec.add_dependency 'scrypt', '~> 3.0.6'
+  # openssl for encrypted key derivation
+  spec.add_dependency "openssl", "~> 3.0"
 
-  spec.add_development_dependency 'pry', '~> 0.1'
-  spec.add_development_dependency 'rake', '>= 12.3.3'
-  spec.add_development_dependency 'rspec', '~> 3.0'
+  # scrypt for encrypted key derivation
+  spec.add_dependency "scrypt", "~> 3.0"
 end

data/lib/eth/abi/constant.rb

@@ -0,0 +1,63 @@
+# Copyright (c) 2016-2022 The Ruby-Eth Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#  -*- encoding : ascii-8bit -*-
+
+# Provides the `Eth` module.
+module Eth
+
+  # Provides a Ruby implementation of the Ethereum Applicatoin Binary Interface (ABI).
+  module Abi
+
+    # Provides commonly used constants, such as zero bytes or zero keys.
+    module Constant
+
+      # The empty byte is defined as "".
+      BYTE_EMPTY = "".freeze
+
+      # The zero byte is 0x00.
+      BYTE_ZERO = "\x00".freeze
+
+      # The byte one is 0x01.
+      BYTE_ONE = "\x01".freeze
+
+      # The size of a 32-bit number.
+      TT32 = (2 ** 32).freeze
+
+      # The size of a 256-bit number.
+      TT256 = (2 ** 256).freeze
+
+      # The maximum possible value of an UInt256.
+      UINT_MAX = (2 ** 256 - 1).freeze
+
+      # The minimum possible value of an UInt256.
+      UINT_MIN = 0.freeze
+
+      # The maximum possible value of an Int256.
+      INT_MAX = (2 ** 255 - 1).freeze
+
+      # The minimum possible value of an Int256.
+      INT_MIN = (-2 ** 255).freeze
+
+      # A hash containing only zeros.
+      HASH_ZERO = ("\x00" * 32).freeze
+
+      # A private key containing only zeros.
+      PRIVKEY_ZERO = ("\x00" * 32).freeze
+
+      # A private key containing only zeros (hex).
+      PRIVKEY_ZERO_HEX = ("0" * 64).freeze
+    end
+  end
+end

data/lib/eth/abi/type.rb

@@ -0,0 +1,177 @@
+# Copyright (c) 2016-2022 The Ruby-Eth Contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -*- encoding : ascii-8bit -*-
+
+# Provides the `Eth` module.
+module Eth
+
+  # Provides a Ruby implementation of the Ethereum Applicatoin Binary Interface (ABI).
+  module Abi
+
+    # Provides a class to handle and parse common ABI types.
+    class Type
+
+      # Provides a specific parser error if type cannot be determined.
+      class ParseError < StandardError; end
+
+      # The base attribute, e.g., `string` or `bytes`
+      attr :base_type
+
+      # The sub-type attribute, e.g., `256` as size of an uint256.
+      attr :sub_type
+
+      # The dimension attribute, e.g., `[10]` for an array of size 10.
+      attr :dimensions
+
+      # Create a new Type object for base types, sub types, and dimensions.
+      # Should use the `Type.parse` parser.
+      #
+      # @param base_type [String] the base-type attribute.
+      # @param sub_type [String] the sub-type attribute.
+      # @param dimensions [Array] the dimension attribute.
+      # @return [Eth::Abi::Type] an ABI type object.
+      def initialize(base_type, sub_type, dimensions)
+        sub_type = sub_type.to_s
+        @base_type = base_type
+        @sub_type = sub_type
+        @dimensions = dimensions
+      end
+
+      # Converts the self.parse method into a constructor.
+      konstructor :parse
+
+      # Attempts to parse a string containing a common Solidity type.
+      # Creates a new Type upon success (using konstructor).
+      #
+      # @param type [String] a common Solidity type.
+      # @return [Eth::Abi::Type] a parsed Type object.
+      # @raise [ParseError] if it fails to parse the type.
+      def parse(type)
+        _, base_type, sub_type, dimension = /([a-z]*)([0-9]*x?[0-9]*)((\[[0-9]*\])*)/.match(type).to_a
+
+        # type dimension can only be numeric
+        dims = dimension.scan(/\[[0-9]*\]/)
+        raise ParseError, "Unknown characters found in array declaration" if dims.join != dimension
+
+        # enforce base types
+        validate_base_type base_type, sub_type
+
+        # return a new Type (using konstructor)
+        sub_type = sub_type.to_s
+        @base_type = base_type
+        @sub_type = sub_type
+        @dimensions = dims.map { |x| x[1...-1].to_i }
+      end
+
+      # Creata new uint256 type used for size.
+      #
+      # @return [Eth::Abi::Type] a uint256 size type.
+      def self.size_type
+        @size_type ||= new("uint", 256, [])
+      end
+
+      # Compares two types for their attributes.
+      #
+      # @param another_type [Eth::Abi::Type] another type to be compared.
+      # @return [Bool] true if all attributes match.
+      def ==(another_type)
+        base_type == another_type.base_type and
+          sub_type == another_type.sub_type and
+          dimensions == another_type.dimensions
+      end
+
+      # Computes the size of a type if possible.
+      #
+      # @return [Integer] the size of the type; or nil if not available.
+      def size
+        s = nil
+        if dimensions.empty?
+          unless ["string", "bytes"].include?(base_type) and sub_type.empty?
+            s = 32
+          end
+        else
+          unless dimensions.last == 0
+            unless nested_sub.is_dynamic?
+              s = dimensions.last * nested_sub.size
+            end
+          end
+        end
+        @size ||= s
+      end
+
+      # Helper to determine whether array is of dynamic size.
+      #
+      # @return [Bool] true if array is of dynamic size.
+      def is_dynamic?
+        size.nil?
+      end
+
+      # Types can have nested sub-types in arrays.
+      #
+      # @return [Eth::Abi::Type] nested sub-type.
+      def nested_sub
+        @nested_sub ||= self.class.new(base_type, sub_type, dimensions[0...-1])
+      end
+
+      private
+
+      def validate_base_type(base_type, sub_type)
+        case base_type
+        when "string"
+
+          # string can not have any suffix
+          raise ParseError, "String type must have no suffix or numerical suffix" unless sub_type.empty?
+        when "bytes"
+
+          # bytes can be no longer than 32 bytes
+          raise ParseError, "Maximum 32 bytes for fixed-length string or bytes" unless sub_type.empty? || sub_type.to_i <= 32
+        when "uint", "int"
+
+          # integers must have a numerical suffix
+          raise ParseError, "Integer type must have numerical suffix" unless sub_type =~ /\A[0-9]+\z/
+
+          # integer size must be valid
+          size = sub_type.to_i
+          raise ParseError, "Integer size out of bounds" unless size >= 8 && size <= 256
+          raise ParseError, "Integer size must be multiple of 8" unless size % 8 == 0
+        when "ureal", "real", "fixed", "ufixed"
+
+          # floats must have valid dimensional suffix
+          raise ParseError, "Real type must have suffix of form <high>x<low>, e.g. 128x128" unless sub_type =~ /\A[0-9]+x[0-9]+\z/
+          high, low = sub_type.split("x").map(&:to_i)
+          total = high + low
+          raise ParseError, "Real size out of bounds (max 32 bytes)" unless total >= 8 && total <= 256
+          raise ParseError, "Real high/low sizes must be multiples of 8" unless high % 8 == 0 && low % 8 == 0
+        when "hash"
+
+          # hashs must have numerical suffix
+          raise ParseError, "Hash type must have numerical suffix" unless sub_type =~ /\A[0-9]+\z/
+        when "address"
+
+          # addresses cannot have any suffix
+          raise ParseError, "Address cannot have suffix" unless sub_type.empty?
+        when "bool"
+
+          # booleans cannot have any suffix
+          raise ParseError, "Bool cannot have suffix" unless sub_type.empty?
+        else
+
+          # we cannot parse arbitrary types such as 'decimal' or 'hex'
+          raise ParseError, "Unknown base type"
+        end
+      end
+    end
+  end
+end