diff --git a/.yardopts b/.yardopts new file mode 100644 index 00000000..6750db65 --- /dev/null +++ b/.yardopts @@ -0,0 +1 @@ +--verbose --fail-on-warning --markup markdown --embed-mixins diff --git a/lib/eth.rb b/lib/eth.rb index 26b136fa..9f871f63 100644 --- a/lib/eth.rb +++ b/lib/eth.rb @@ -12,11 +12,11 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth end -# Loads the `Eth` module classes. +# Loads the {Eth} module classes. require "eth/abi" require "eth/api" require "eth/address" diff --git a/lib/eth/abi.rb b/lib/eth/abi.rb index 9ebf7083..28046afa 100644 --- a/lib/eth/abi.rb +++ b/lib/eth/abi.rb @@ -18,7 +18,7 @@ require "eth/abi/type" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides a Ruby implementation of the Ethereum Applicatoin Binary Interface (ABI). @@ -69,7 +69,7 @@ def encode(types, args) # Encodes a specific value, either static or dynamic. # # @param type [Eth::Abi::Type] type to be encoded. - # @param arg [String, Number] value to be encoded. + # @param arg [String|Number] value to be encoded. # @return [String] the encoded type. # @raise [EncodingError] if value does not match type. def encode_type(type, arg) @@ -111,7 +111,7 @@ def encode_type(type, arg) # Encodes primitive types. # # @param type [Eth::Abi::Type] type to be encoded. - # @param arg [String, Number] value to be encoded. + # @param arg [String|Number] value to be encoded. # @return [String] the encoded primitive type. # @raise [EncodingError] if value does not match type. # @raise [ValueOutOfBounds] if value is out of bounds for type. diff --git a/lib/eth/abi/type.rb b/lib/eth/abi/type.rb index 9ab72e08..81dba774 100644 --- a/lib/eth/abi/type.rb +++ b/lib/eth/abi/type.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides a Ruby implementation of the Ethereum Applicatoin Binary Interface (ABI). @@ -26,7 +26,7 @@ class Type # Provides a specific parser error if type cannot be determined. class ParseError < StandardError; end - # The base attribute, e.g., `string` or `bytes` + # The base attribute, e.g., `string` or `bytes`. attr :base_type # The sub-type attribute, e.g., `256` as size of an uint256. @@ -36,7 +36,7 @@ class ParseError < StandardError; end attr :dimensions # Create a new Type object for base types, sub types, and dimensions. - # Should use the `Type.parse` parser. + # Should not be used; use {Type.parse} instead. # # @param base_type [String] the base-type attribute. # @param sub_type [String] the sub-type attribute. @@ -75,7 +75,7 @@ def parse(type) @dimensions = dims.map { |x| x[1...-1].to_i } end - # Creata new uint256 type used for size. + # Creates a new uint256 type used for size. # # @return [Eth::Abi::Type] a uint256 size type. def self.size_type @@ -85,7 +85,7 @@ def self.size_type # Compares two types for their attributes. # # @param another_type [Eth::Abi::Type] another type to be compared. - # @return [Bool] true if all attributes match. + # @return [Boolean] true if all attributes match. def ==(another_type) base_type == another_type.base_type and sub_type == another_type.sub_type and @@ -111,9 +111,9 @@ def size @size ||= s end - # Helper to determine whether array is of dynamic size. + # Helpes to determine whether array is of dynamic size. # - # @return [Bool] true if array is of dynamic size. + # @return [Boolean] true if array is of dynamic size. def is_dynamic? size.nil? end diff --git a/lib/eth/address.rb b/lib/eth/address.rb index 350cff84..7182a270 100644 --- a/lib/eth/address.rb +++ b/lib/eth/address.rb @@ -12,10 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # The `Eth::Address` class to handle checksummed Ethereum addresses. + # The {Eth::Address} class to handle checksummed Ethereum addresses. class Address # Provides a special checksum error if EIP-55 is violated. @@ -24,7 +24,7 @@ class CheckSumError < StandardError; end # The prefixed and checksummed Ethereum address. attr_reader :address - # Constructor of the `Eth::Address` class. Creates a new hex + # Constructor of the {Eth::Address} class. Creates a new hex # prefixed address. # # @param address [String] hex string representing an ethereum address. @@ -38,9 +38,9 @@ def initialize(address) end end - # Check that the address is valid. + # Checks that the address is valid. # - # @return [Bool] true if valid address. + # @return [Boolean] true if valid address. def valid? if !matches_any_format? false diff --git a/lib/eth/api.rb b/lib/eth/api.rb index fe84c31e..2ead069d 100644 --- a/lib/eth/api.rb +++ b/lib/eth/api.rb @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides the `Eth::Api` module grouping known RPC commands. diff --git a/lib/eth/chain.rb b/lib/eth/chain.rb index c171d2d9..818968b7 100644 --- a/lib/eth/chain.rb +++ b/lib/eth/chain.rb @@ -12,82 +12,85 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # Encapsulates `Chain` IDs and utilities for EIP-155 compatibility. - # ref: https://eips.ethereum.org/EIPS/eip-155 + # Encapsulates {Eth::Chain} IDs and utilities for EIP-155 compatibility. + # Ref: https://eips.ethereum.org/EIPS/eip-155 module Chain extend self # Provides a special replay protection error if EIP-155 is violated. class ReplayProtectionError < StandardError; end - # Chain ID for Ethereum mainnet + # Chain ID for Ethereum mainnet. ETHEREUM = 1.freeze - # Chain ID for Expanse mainnet + # Chain ID for Expanse mainnet. EXPANSE = 2.freeze - # Chain ID for Optimistic Ethereum mainnet + # Chain ID for Optimistic Ethereum mainnet. OPTIMISM = 10.freeze - # Chain ID for Ethereum Classic mainnet + # Chain ID for Ethereum Classic mainnet. CLASSIC = 61.freeze - # Chain ID for POA Network mainnet + # Chain ID for POA Network mainnet. POA_NET = 99.freeze - # Chain ID for xDAI mainnet + # Chain ID for Gnosis mainnet. XDAI = 100.freeze - # Chain ID for Arbitrum mainnet + # Chain ID for Arbitrum mainnet. ARBITRUM = 42161.freeze - # Chain ID for Morden (Ethereum) testnet + # Chain ID for Morden (Ethereum) testnet. MORDEN = 2.freeze - # Chain ID for Ropsten testnet + # Chain ID for Ropsten testnet. ROPSTEN = 3.freeze - # Chain ID for Rinkeby testnet + # Chain ID for Rinkeby testnet. RINKEBY = 4.freeze - # Chain ID for Goerli testnet + # Chain ID for Goerli testnet. GOERLI = 5.freeze - # Chain ID for Kotti testnet + # Chain ID for Kotti testnet. KOTTI = 6.freeze - # Chain ID for Kovan testnet + # Chain ID for Kovan testnet. KOVAN = 42.freeze - # Chain ID for Morden (Classic) testnet + # Chain ID for Morden (Classic) testnet. MORDEN_CLASSIC = 62.freeze - # Chain ID for Mordor testnet + # Chain ID for Mordor testnet. MORDOR = 63.freeze - # Chain ID for Optimistik Kovan testnet + # Chain ID for Optimistik Kovan testnet. KOVAN_OPTIMISM = 69.freeze - # Chain ID for Arbitrum xDAI testnet + # Chain ID for Arbitrum xDAI testnet. XDAI_ARBITRUM = 200.freeze - # Chain ID for Optimistic Goerli testnet + # Chain ID for Optimistic Goerli testnet. GOERLI_OPTIMISM = 420.freeze - # Chain ID for Arbitrum Rinkeby testnet + # Chain ID for Arbitrum Rinkeby testnet. RINKEBY_ARBITRUM = 421611.freeze - # Chain ID for the geth private network preset + # Chain ID for Sepolia testnet. + SEPOLIA = 11155111.freeze + + # Chain ID for the geth private network preset. PRIVATE_GETH = 1337.freeze # Indicates wether the given `v` indicates a legacy chain value # without EIP-155 replay protection. # - # @param v [Integer] the signature's `v` value - # @return [Boolean] true if legacy value + # @param v [Integer] the signature's `v` value. + # @return [Boolean] true if legacy value. def is_legacy?(v) [27, 28].include? v end @@ -95,7 +98,7 @@ def is_legacy?(v) # Convert a given `v` value to an ECDSA recovery id for the given # EIP-155 chain ID. # - # @param v [Integer] the signature's `v` value + # @param v [Integer] the signature's `v` value. # @param chain_id [Integer] the chain id the signature was generated on. # @return [Integer] the recovery id corresponding to `v`. # @raise [ReplayProtectionError] if the given `v` is invalid. @@ -134,10 +137,10 @@ def to_v(recovery_id, chain_id = nil) end # Converst a `v` value into a chain ID. This does not work for legacy signatures - # with v < 36 that do not conform with EIP-155. + # with `v < 36` that do not conform with EIP-155. # # @param v [Integer] the signature's `v` value. - # @return [Integer] the chain id as per EIP-155 or nil if there is no replay protection. + # @return [Integer] the chain id as per EIP-155 or `nil` if there is no replay protection. def to_chain_id(v) return nil if v < 36 chain_id = (v - 35) / 2 diff --git a/lib/eth/client.rb b/lib/eth/client.rb index 9d281355..941fe814 100644 --- a/lib/eth/client.rb +++ b/lib/eth/client.rb @@ -12,10 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # Provides the `Eth::Client` super-class to connect to Ethereum + # Provides the {Eth::Client} super-class to connect to Ethereum # network's RPC-API endpoints (IPC or HTTP). class Client @@ -28,13 +28,13 @@ class Client # The connected network's client coinbase. attr_accessor :default_account - # The transaction max priority fee per gas in Wei. + # The default transaction max priority fee per gas in Wei. attr_accessor :max_priority_fee_per_gas - # The transaction max fee per gas in Wei. + # The default transaction max fee per gas in Wei. attr_accessor :max_fee_per_gas - # The gas limit for the transaction. + # The default gas limit for the transaction. attr_accessor :gas_limit # Creates a new RPC-Client, either by providing an HTTP/S host or @@ -50,7 +50,8 @@ def self.create(host) raise ArgumentError, "Unable to detect client type!" end - # Constructor for the Eth::Client super-class. + # Constructor for the {Eth::Client} super-class. Should not be used; + # use {Client.create} intead. def initialize(_) @id = 0 @max_priority_fee_per_gas = 0 @@ -95,7 +96,7 @@ def get_nonce(address) # @param destination [Eth::Address] the destination address. # @param amount [Integer] the transfer amount in Wei. # @param sender_key [Eth::Key] the sender private key. - # @param legacy [Bool] enables legacy transactions (pre-EIP-1559). + # @param legacy [Boolean] enables legacy transactions (pre-EIP-1559). # @return [String] the transaction hash. def transfer_and_wait(destination, amount, sender_key = nil, legacy = false) wait_for_tx(transfer(destination, amount, sender_key, legacy)) @@ -108,7 +109,7 @@ def transfer_and_wait(destination, amount, sender_key = nil, legacy = false) # @param destination [Eth::Address] the destination address. # @param amount [Integer] the transfer amount in Wei. # @param sender_key [Eth::Key] the sender private key. - # @param legacy [Bool] enables legacy transactions (pre-EIP-1559). + # @param legacy [Boolean] enables legacy transactions (pre-EIP-1559). # @return [String] the transaction hash. def transfer(destination, amount, sender_key = nil, legacy = false) params = { @@ -159,7 +160,7 @@ def reset_id # Checkes wether a transaction is mined or not. # # @param hash [String] the transaction hash. - # @return [Bool] true if included in a block. + # @return [Boolean] true if included in a block. def is_mined_tx?(hash) mined_tx = eth_get_transaction_by_hash hash !mined_tx.nil? && !mined_tx["result"].nil? && !mined_tx["result"]["blockNumber"].nil? diff --git a/lib/eth/client/http.rb b/lib/eth/client/http.rb index 4e4dec46..e067d150 100644 --- a/lib/eth/client/http.rb +++ b/lib/eth/client/http.rb @@ -14,7 +14,7 @@ require "net/http" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an HTTP/S-RPC client. @@ -32,7 +32,8 @@ class Client::Http < Client # Attribute indicator for SSL. attr_reader :ssl - # Constructor for the HTTP Client. + # Constructor for the HTTP Client. Should not be used; use + # {Client.create} intead. # # @param host [String] an URI pointing to an HTTP RPC-API. def initialize(host) diff --git a/lib/eth/client/ipc.rb b/lib/eth/client/ipc.rb index eb539a37..638d166f 100644 --- a/lib/eth/client/ipc.rb +++ b/lib/eth/client/ipc.rb @@ -14,7 +14,7 @@ require "socket" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an IPC-RPC client. @@ -23,7 +23,8 @@ class Client::Ipc < Client # The path of the IPC socket. attr_accessor :path - # Constructor for the IPC Client. + # Constructor for the IPC Client. Should not be used; use + # {Client.create} intead. # # @param path [String] an URI pointing to an IPC RPC-API. def initialize(path) diff --git a/lib/eth/constant.rb b/lib/eth/constant.rb index 00f2767e..7f075adb 100644 --- a/lib/eth/constant.rb +++ b/lib/eth/constant.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides commonly used constants, such as zero bytes or zero keys. @@ -50,12 +50,6 @@ module Constant # 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 - # The RLP short length limit. SHORT_LENGTH_LIMIT = 56.freeze diff --git a/lib/eth/eip712.rb b/lib/eth/eip712.rb index de1a3d74..d101132d 100644 --- a/lib/eth/eip712.rb +++ b/lib/eth/eip712.rb @@ -12,11 +12,11 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Defines handy tools for encoding typed structured data as per EIP-712. - # ref: https://eips.ethereum.org/EIPS/eip-712 + # Ref: https://eips.ethereum.org/EIPS/eip-712 module Eip712 extend self diff --git a/lib/eth/key.rb b/lib/eth/key.rb index 43238e23..f26ae9b0 100644 --- a/lib/eth/key.rb +++ b/lib/eth/key.rb @@ -18,28 +18,28 @@ require "scrypt" require "securerandom" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # The `Eth::Key` class to handle Secp256k1 private/public key-pairs. + # The {Eth::Key} class to handle Secp256k1 private/public key-pairs. class Key - # The Eth::Key::Decrypter class to handle PBKDF2-SHA-256 decryption. + # The {Eth::Key::Decrypter} class to handle PBKDF2-SHA-256 decryption. autoload :Decrypter, "eth/key/decrypter" - # The Eth::Key::Encrypter class to handle PBKDF2-SHA-256 encryption. + # The {Eth::Key::Encrypter} class to handle PBKDF2-SHA-256 encryption. autoload :Encrypter, "eth/key/encrypter" - # The `Secp256k1::PrivateKey` of the `Eth::Key` pair. + # The `Secp256k1::PrivateKey` of the {Eth::Key} pair. attr_reader :private_key - # The `Secp256k1::PublicKey` of the `Eth::Key` pair. + # The `Secp256k1::PublicKey` of the {Eth::Key} pair. attr_reader :public_key - # Constructor of the `Eth::Key` class. Creates a new random key-pair + # Constructor of the {Eth::Key} class. Creates a new random key-pair # if no `priv` key is provided. # - # @param priv [String] binary string of private key data (optional). + # @param priv [String] binary string of private key data. def initialize(priv: nil) # Creates a new, randomized libsecp256k1 context. @@ -63,9 +63,10 @@ def initialize(priv: nil) end # Signs arbitrary data without validation. Should not be used unless really - # desired. See also: personal_sign, sign_typed_data. + # desired. See also: {Key.personal_sign}, {Key.sign_typed_data}, and + # {Signature.recover}. # - # @param blob [String] that arbitrary data to be signed. + # @param blob [Object] that arbitrary data to be signed. # @param chain_id [Integer] the chain id the signature should be generated on. # @return [String] a hexa-decimal signature. def sign(blob, chain_id = nil) @@ -81,9 +82,11 @@ def sign(blob, chain_id = nil) Util.bin_to_hex signature.pack "c*" end - # Prefixes a message with "\x19Ethereum Signed Message:" and signs + # Prefixes a message with `\x19Ethereum Signed Message:` and signs # it in the common way used by many web3 wallets. Complies with - # EIP-191 prefix 0x19 and version byte 0x45 (E). + # EIP-191 prefix `0x19` and version byte `0x45` (`E`). See also + # {Signature.personal_recover}. + # Ref: https://eips.ethereum.org/EIPS/eip-191 # # @param message [String] the message string to be prefixed and signed. # @param chain_id [Integer] the chain id the signature should be generated on. @@ -95,8 +98,10 @@ def personal_sign(message, chain_id = nil) end # Prefixes, hashes, and signes a typed data structure in the common - # way used by many web3 wallets. Complies with EIP-191 prefix 0x19 - # and EIP-712 version byte 0x01. Supports `V3`, `V4`. + # way used by many web3 wallets. Complies with EIP-191 prefix `0x19` + # and EIP-712 version byte `0x01`. Supports `V3`, `V4`. See also + # {Signature.recover_typed_data}. + # Ref: https://eips.ethereum.org/EIPS/eip-712 # # @param typed_data [Array] all the data in the typed data structure to be signed. # @param chain_id [Integer] the chain id the signature should be generated on. @@ -114,7 +119,7 @@ def private_hex end # Exports the private key bytes in a wrapper function to maintain - # backward-compatibility with older versions of `Eth::Key`. + # backward-compatibility with older versions of {Eth::Key}. # # @return [String] private key as packed byte-string. def private_bytes @@ -138,7 +143,7 @@ def public_hex_compressed end # Exports the uncompressed public key bytes in a wrapper function to - # maintain backward-compatibility with older versions of `Eth::Key`. + # maintain backward-compatibility with older versions of {Eth::Key}. # # @return [String] uncompressed public key as packed byte-string. def public_bytes diff --git a/lib/eth/key/decrypter.rb b/lib/eth/key/decrypter.rb index 0835d1fc..e3afb0d5 100644 --- a/lib/eth/key/decrypter.rb +++ b/lib/eth/key/decrypter.rb @@ -12,38 +12,40 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # The Eth::Key::Decrypter class to handle PBKDF2-SHA-256 decryption. + # The {Eth::Key::Decrypter} class to handle PBKDF2-SHA-256 decryption. class Key::Decrypter # Provides a specific decrypter error if decryption fails. class DecrypterError < StandardError; end - # Class method `Eth::Key::Decrypter.perform` + # Class method {Eth::Key::Decrypter.perform} to perform an keystore + # decryption. # - # @param data [JSON] encryption data including cypherkey - # @param password [String] password to decrypt the key - # @return [Eth::Key] decrypted key-pair + # @param data [JSON] encryption data including cypherkey. + # @param password [String] password to decrypt the key. + # @return [Eth::Key] decrypted key-pair. def self.perform(data, password) new(data, password).perform end - # Constructor of the `Eth::Key::Decrypter` class for secret key - # encryption. + # Constructor of the {Eth::Key::Decrypter} class for secret key + # decryption. Should not be used; use {Eth::Key::Decrypter.perform} + # instead. # - # @param data [JSON] encryption data including cypherkey - # @param password [String] password to decrypt the key + # @param data [JSON] encryption data including cypherkey. + # @param password [String] password to decrypt the key. def initialize(data, password) data = JSON.parse(data) if data.is_a? String @data = data @password = password end - # Method to decrypt key using password + # Method to decrypt key using password. # - # @return [String] decrypted key + # @return [Eth::Key] decrypted key. def perform derive_key password check_macs diff --git a/lib/eth/key/encrypter.rb b/lib/eth/key/encrypter.rb index 9c0d5ec9..d9cd6910 100644 --- a/lib/eth/key/encrypter.rb +++ b/lib/eth/key/encrypter.rb @@ -12,44 +12,45 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # The Eth::Key::Encrypter class to handle PBKDF2-SHA-256 encryption. + # The {Eth::Key::Encrypter} class to handle PBKDF2-SHA-256 encryption. class Key::Encrypter # Provides a specific encrypter error if decryption fails. class EncrypterError < StandardError; end - # Class method `Eth::Key::Encrypter.perform` to performa an key-store + # Class method {Eth::Key::Encrypter.perform} to performa an key-store # encryption. # - # @param key [Eth::Key] representing a secret key-pair used for encryption - # @param options [Hash] the options to encrypt with - # @option options [String] :kdf key derivation function defaults to pbkdf2 - # @option options [String] :id uuid given to the secret key - # @option options [String] :iterations number of iterations for the hash function - # @option options [String] :salt passed to PBKDF - # @option options [String] :iv 128-bit initialisation vector for the cipher - # @option options [Integer] :parallelization parallelization factor for scrypt, defaults to 8 - # @option options [Integer] :block_size for scrypt, defaults to 1 - # @return [JSON] formatted with encrypted key (cyphertext) and [other identifying data](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition#pbkdf2-sha-256) + # @param key [Eth::Key] representing a secret key-pair used for encryption. + # @param options [Hash] the options to encrypt with. + # @option options [String] :kdf key derivation function defaults to pbkdf2. + # @option options [String] :id uuid given to the secret key. + # @option options [String] :iterations number of iterations for the hash function. + # @option options [String] :salt passed to PBKDF. + # @option options [String] :iv 128-bit initialisation vector for the cipher. + # @option options [Integer] :parallelization parallelization factor for scrypt, defaults to 8. + # @option options [Integer] :block_size for scrypt, defaults to 1. + # @return [JSON] formatted with encrypted key (cyphertext) and [other identifying data](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition#pbkdf2-sha-256). def self.perform(key, password, options = {}) new(key, options).perform(password) end - # Constructor of the `Eth::Key::Encrypter` class for secret key - # encryption. + # Constructor of the {Eth::Key::Encrypter} class for secret key + # encryption. Should not be used; use {Eth::Key::Encrypter.perform} + # instead. # - # @param key [Eth::Key] representing a secret key-pair used for encryption - # @param options [Hash] the options to encrypt with - # @option options [String] :kdf key derivation function defaults to pbkdf2 - # @option options [String] :id uuid given to the secret key - # @option options [String] :iterations number of iterations for the hash function - # @option options [String] :salt passed to PBKDF - # @option options [String] :iv 128-bit initialisation vector for the cipher - # @option options [Integer] :parallelization parallelization factor for scrypt, defaults to 8 - # @option options [Integer] :block_size for scrypt, defaults to 1 + # @param key [Eth::Key] representing a secret key-pair used for encryption. + # @param options [Hash] the options to encrypt with. + # @option options [String] :kdf key derivation function defaults to pbkdf2. + # @option options [String] :id uuid given to the secret key. + # @option options [String] :iterations number of iterations for the hash function. + # @option options [String] :salt passed to PBKDF. + # @option options [String] :iv 128-bit initialisation vector for the cipher. + # @option options [Integer] :parallelization parallelization factor for scrypt, defaults to 8. + # @option options [Integer] :block_size for scrypt, defaults to 1. def initialize(key, options = {}) key = Key.new(priv: key) if key.is_a? String @key = key @@ -65,7 +66,7 @@ def initialize(key, options = {}) # Encrypt the key with a given password. # # @param password [String] a secret key used for encryption - # @return [String] a json-formatted keystore string. + # @return [String] a JSON-formatted keystore string. def perform(password) derive_key password encrypt diff --git a/lib/eth/rlp.rb b/lib/eth/rlp.rb index a1b18198..a59c385d 100644 --- a/lib/eth/rlp.rb +++ b/lib/eth/rlp.rb @@ -19,14 +19,14 @@ require "eth/rlp/sedes" require "eth/util" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. module Rlp extend self - # The Rlp module exposes a variety of exceptions grouped as RlpException. + # The Rlp module exposes a variety of exceptions grouped as {RlpException}. class RlpException < StandardError; end # An error-type to point out RLP-encoding errors. @@ -41,10 +41,10 @@ class SerializationError < RlpException; end # An error-type to point out RLP-type serialization errors. class DeserializationError < RlpException; end - # A wrapper to represent already RLP encoded data. + # A wrapper to represent already RLP-encoded data. class Data < String; end - # Performes an Eth::Rlp::Encoder on any ruby object. + # Performes an {Eth::Rlp::Encoder} on any ruby object. # # @param obj [Object] any ruby object. # @return [String] a packed, RLP-encoded item. @@ -52,7 +52,7 @@ def encode(obj) Rlp::Encoder.perform obj end - # Performes an Eth::Rlp::Decoder on any RLP-encoded item. + # Performes an {Eth::Rlp::Decoder} on any RLP-encoded item. # # @param rlp [String] a packed, RLP-encoded item. # @return [Object] a decoded ruby object. diff --git a/lib/eth/rlp/decoder.rb b/lib/eth/rlp/decoder.rb index 5dc901b6..6cb3e834 100644 --- a/lib/eth/rlp/decoder.rb +++ b/lib/eth/rlp/decoder.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. @@ -30,7 +30,6 @@ module Decoder # @return [Object] the decoded and maybe deserialized object. # @raise [Eth::Rlp::DecodingError] if the input string does not end after # the root item. - # @raise [Eht::Rlp::DeserializationError] if the deserialization fails. def perform(rlp) rlp = Util.hex_to_bin rlp if Util.is_hex? rlp rlp = Util.str_to_bytes rlp diff --git a/lib/eth/rlp/encoder.rb b/lib/eth/rlp/encoder.rb index 0d6385e6..e79dfabd 100644 --- a/lib/eth/rlp/encoder.rb +++ b/lib/eth/rlp/encoder.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. diff --git a/lib/eth/rlp/sedes.rb b/lib/eth/rlp/sedes.rb index 4503e3a9..6e5d00ae 100644 --- a/lib/eth/rlp/sedes.rb +++ b/lib/eth/rlp/sedes.rb @@ -18,7 +18,7 @@ require "eth/rlp/sedes/binary" require "eth/rlp/sedes/list" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. @@ -27,13 +27,13 @@ module Rlp # Provides serializable and deserializable types (SeDes). module Sedes - # Provides a singleton Eth::Rlp::Sedes class to infer objects and types. + # Provides a singleton {Eth::Rlp::Sedes} class to infer objects and types. class << self # Tries to find a sedes objects suitable for a given Ruby object. # - # The sedes objects considered are `obj`'s class, `big_endian_int` and - # `binary`. If `obj` is a list, an `Eth::Rlp::Sedes::List` will be + # The sedes objects considered are `obj`'s class, {big_endian_int} and + # {binary}. If `obj` is a list, an {Eth::Rlp::Sedes::List} will be # constructed recursively. # # @param obj [Object] the Ruby object for which to find a sedes object. diff --git a/lib/eth/rlp/sedes/big_endian_int.rb b/lib/eth/rlp/sedes/big_endian_int.rb index 93e22184..06c888d3 100644 --- a/lib/eth/rlp/sedes/big_endian_int.rb +++ b/lib/eth/rlp/sedes/big_endian_int.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. diff --git a/lib/eth/rlp/sedes/binary.rb b/lib/eth/rlp/sedes/binary.rb index b2ad2ee8..1f751b29 100644 --- a/lib/eth/rlp/sedes/binary.rb +++ b/lib/eth/rlp/sedes/binary.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. diff --git a/lib/eth/rlp/sedes/list.rb b/lib/eth/rlp/sedes/list.rb index 7ca85d41..b999a06e 100644 --- a/lib/eth/rlp/sedes/list.rb +++ b/lib/eth/rlp/sedes/list.rb @@ -14,7 +14,7 @@ # -*- encoding : ascii-8bit -*- -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides an recursive-length prefix (RLP) encoder and decoder. diff --git a/lib/eth/signature.rb b/lib/eth/signature.rb index bd324fa3..3ecb243a 100644 --- a/lib/eth/signature.rb +++ b/lib/eth/signature.rb @@ -14,7 +14,7 @@ require "rbsecp256k1" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Defines handy tools for verifying and recovering signatures. @@ -30,21 +30,22 @@ class SignatureError < StandardError; end # EIP-712 version byte 0x01 EIP712_VERSION_BYTE = "\x01".freeze - # Prefix message as per EIP-191 with 0x19 to ensure the data is not + # Prefix message as per EIP-191 with `0x19` to ensure the data is not # valid RLP and thus not mistaken for a transaction. - # EIP-191 Version byte: 0x45 (E) - # ref: https://eips.ethereum.org/EIPS/eip-191 + # EIP-191 Version byte: `0x45` (`E`) + # Ref: https://eips.ethereum.org/EIPS/eip-191 # # @param message [String] the message string to be prefixed. - # @return [String] an EIP-191 prefixed string + # @return [String] an EIP-191 prefixed string. def prefix_message(message) "#{EIP191_PREFIX_BYTE}Ethereum Signed Message:\n#{message.size}#{message}" end - # Dissects a signature blob of 65 bytes into its r, s, and v values. + # Dissects a signature blob of 65+ bytes into its `r`, `s`, and `v` + # values. # - # @param signature [String] a Secp256k1 signature. - # @return [String, String, String] the r, s, and v values. + # @param signature [String] a concatenated Secp256k1 signature string. + # @return [String, String, String] the `r`, `s`, and `v` values. # @raise [SignatureError] if signature is of unknown size. def dissect(signature) signature = Util.bin_to_hex signature unless Util.is_hex? signature @@ -79,6 +80,7 @@ def recover(blob, signature, chain_id = Chain::ETHEREUM) # Recovers a public key from a prefixed, personal message and # a signature on a given chain. (EIP-191) + # Ref: https://eips.ethereum.org/EIPS/eip-191 # # @param message [String] the message string. # @param signature [String] the hex string containing the signature. @@ -92,6 +94,7 @@ def personal_recover(message, signature, chain_id = Chain::ETHEREUM) # Recovers a public key from a typed data structure and a signature # on a given chain. (EIP-712) + # Ref: https://eips.ethereum.org/EIPS/eip-712 # # @param typed_data [Array] all the data in the typed data structure to be recovered. # @param signature [String] the hex string containing the signature. diff --git a/lib/eth/tx.rb b/lib/eth/tx.rb index ab23380b..130a0231 100644 --- a/lib/eth/tx.rb +++ b/lib/eth/tx.rb @@ -20,14 +20,14 @@ require "eth/tx/legacy" require "eth/unit" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides the `Tx` module supporting various transaction types. module Tx extend self - # Provides a special transactoin error if transaction type is unknown. + # Provides a special transaction error if transaction type is unknown. class TransactionTypeError < TypeError; end # Provides an decoder error if transaction cannot be decoded. diff --git a/lib/eth/tx/eip1559.rb b/lib/eth/tx/eip1559.rb index e2e01f06..ba6b16c6 100644 --- a/lib/eth/tx/eip1559.rb +++ b/lib/eth/tx/eip1559.rb @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides the `Tx` module supporting various transaction types. @@ -20,9 +20,11 @@ module Tx # Provides support for EIP-1559 transactions utilizing EIP-2718 # types and envelopes. + # Ref: https://eips.ethereum.org/EIPS/eip-1559 class Eip1559 # The EIP-155 Chain ID. + # Ref: https://eips.ethereum.org/EIPS/eip-155 attr_reader :chain_id # The transaction nonce provided by the signer. @@ -47,6 +49,7 @@ class Eip1559 attr_reader :payload # An optional EIP-2930 access list. + # Ref: https://eips.ethereum.org/EIPS/eip-2930 attr_reader :access_list # The signature's y-parity byte (not v). @@ -66,6 +69,7 @@ class Eip1559 # Create a type-2 (EIP-1559) transaction payload object that # can be prepared for envelope, signature and broadcast. + # Ref: https://eips.ethereum.org/EIPS/eip-1559 # # @param params [Hash] all necessary transaction fields. # @option params [Integer] :chain_id the chain ID. @@ -78,6 +82,7 @@ class Eip1559 # @option params [Integer] :value the transaction value. # @option params [String] :data the transaction data payload. # @option params [Array] :access_list an optional access list. + # @raise [ParameterError] if gas limit is too low. def initialize(params) fields = { recovery_id: nil, r: 0, s: 0 }.merge params @@ -122,7 +127,7 @@ def initialize(params) # Overloads the constructor for decoding raw transactions and creating unsigned copies. konstructor :decode, :unsigned_copy - # Decodes a raw transaction hex into an Eth::Tx::Eip1559 + # Decodes a raw transaction hex into an {Eth::Tx::Eip1559} # transaction object. # # @param hex [String] the raw transaction hex-string. @@ -222,8 +227,8 @@ def unsigned_copy(tx) # # @param key [Eth::Key] the key-pair to use for signing. # @return [String] a transaction hash. - # @raise [SignatureError] if transaction is already signed. - # @raise [SignatureError] if sender address does not match signing key. + # @raise [Signature::SignatureError] if transaction is already signed. + # @raise [Signature::SignatureError] if sender address does not match signing key. def sign(key) if Tx.is_signed? self raise Signature::SignatureError, "Transaction is already signed!" @@ -250,7 +255,7 @@ def sign(key) # with an EIP-1559 type prefix. # # @return [String] a raw, RLP-encoded EIP-1559 type transaction object. - # @raise [SignatureError] if the transaction is not yet signed. + # @raise [Signature::SignatureError] if the transaction is not yet signed. def encoded unless Tx.is_signed? self raise Signature::SignatureError, "Transaction is not signed!" diff --git a/lib/eth/tx/eip2930.rb b/lib/eth/tx/eip2930.rb index f14bf101..f0675032 100644 --- a/lib/eth/tx/eip2930.rb +++ b/lib/eth/tx/eip2930.rb @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides the `Tx` module supporting various transaction types. @@ -20,9 +20,11 @@ module Tx # Provides legacy support for transactions on blockchains that do not # implement EIP-1559 but still want to utilize EIP-2718 envelopes. + # Ref: https://eips.ethereum.org/EIPS/eip-2930 class Eip2930 # The EIP-155 Chain ID. + # Ref: https://eips.ethereum.org/EIPS/eip-155 attr_reader :chain_id # The transaction nonce provided by the signer. @@ -44,9 +46,10 @@ class Eip2930 attr_reader :payload # An optional EIP-2930 access list. + # Ref: https://eips.ethereum.org/EIPS/eip-2930 attr_reader :access_list - # The signature's y-parity byte (not v). + # The signature's `y`-parity byte (not `v`). attr_reader :signature_y_parity # The signature `r` value. @@ -64,6 +67,7 @@ class Eip2930 # Create a legacy type-1 (EIP-2930) transaction payload object that # can be prepared for envelope, signature and broadcast. Should not # be used unless there is no EIP-1559 support. + # Ref: https://eips.ethereum.org/EIPS/eip-2930 # # # @param params [Hash] all necessary transaction fields. @@ -76,6 +80,7 @@ class Eip2930 # @option params [Integer] :value the transaction value. # @option params [String] :data the transaction data payload. # @option params [Array] :access_list an optional access list. + # @raise [ParameterError] if gas limit is too low. def initialize(params) fields = { recovery_id: nil, r: 0, s: 0 }.merge params @@ -119,7 +124,7 @@ def initialize(params) # Overloads the constructor for decoding raw transactions and creating unsigned copies. konstructor :decode, :unsigned_copy - # Decodes a raw transaction hex into an Eth::Tx::Eip2930 + # Decodes a raw transaction hex into an {Eth::Tx::Eip2930} # transaction object. # # @param hex [String] the raw transaction hex-string. @@ -216,8 +221,8 @@ def unsigned_copy(tx) # # @param key [Eth::Key] the key-pair to use for signing. # @return [String] a transaction hash. - # @raise [SignatureError] if transaction is already signed. - # @raise [SignatureError] if sender address does not match signing key. + # @raise [Signature::SignatureError] if transaction is already signed. + # @raise [Signature::SignatureError] if sender address does not match signing key. def sign(key) if Tx.is_signed? self raise Signature::SignatureError, "Transaction is already signed!" @@ -244,7 +249,7 @@ def sign(key) # with an EIP-2930 type prefix. # # @return [String] a raw, RLP-encoded EIP-2930 type transaction object. - # @raise [SignatureError] if the transaction is not yet signed. + # @raise [Signature::SignatureError] if the transaction is not yet signed. def encoded unless Tx.is_signed? self raise Signature::SignatureError, "Transaction is not signed!" diff --git a/lib/eth/tx/legacy.rb b/lib/eth/tx/legacy.rb index 74e007cc..a391cb72 100644 --- a/lib/eth/tx/legacy.rb +++ b/lib/eth/tx/legacy.rb @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides the `Tx` module supporting various transaction types. @@ -50,6 +50,7 @@ class Legacy attr_reader :signature_s # The EIP-155 chain ID field. + # Ref: https://eips.ethereum.org/EIPS/eip-155 attr_reader :chain_id # The sender address. @@ -71,6 +72,7 @@ class Legacy # @option params [Integer] :value the transaction value. # @option params [String] :data the transaction data payload. # @param chain_id [Integer] the EIP-155 Chain ID. + # @raise [ParameterError] if gas limit is too low. def initialize(params, chain_id = Chain::ETHEREUM) fields = { v: chain_id, r: 0, s: 0 }.merge params @@ -111,7 +113,7 @@ def initialize(params, chain_id = Chain::ETHEREUM) # overloads the constructor for decoding raw transactions and creating unsigned copies konstructor :decode, :unsigned_copy - # Decodes a raw transaction hex into an Eth::Tx::Legacy + # Decodes a raw transaction hex into an {Eth::Tx::Legacy} # transaction object. # # @param hex [String] the raw transaction hex-string. @@ -199,8 +201,8 @@ def unsigned_copy(tx) # # @param key [Eth::Key] the key-pair to use for signing. # @return [String] a transaction hash. - # @raise [SignatureError] if transaction is already signed. - # @raise [SignatureError] if sender address does not match signing key. + # @raise [Signature::SignatureError] if transaction is already signed. + # @raise [Signature::SignatureError] if sender address does not match signing key. def sign(key) if Tx.is_signed? self raise Signature::SignatureError, "Transaction is already signed!" @@ -225,7 +227,7 @@ def sign(key) # Encodes a raw transaction object. # # @return [String] a raw, RLP-encoded legacy transaction. - # @raise [SignatureError] if the transaction is not yet signed. + # @raise [Signature::SignatureError] if the transaction is not yet signed. def encoded unless Tx.is_signed? self raise Signature::SignatureError, "Transaction is not signed!" diff --git a/lib/eth/unit.rb b/lib/eth/unit.rb index 5506f515..84b0fc6f 100644 --- a/lib/eth/unit.rb +++ b/lib/eth/unit.rb @@ -14,7 +14,7 @@ require "bigdecimal" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth # Provides constants for common Ethereum units. diff --git a/lib/eth/util.rb b/lib/eth/util.rb index a8144892..a4d4f648 100644 --- a/lib/eth/util.rb +++ b/lib/eth/util.rb @@ -14,10 +14,10 @@ require "digest/keccak" -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # Defines handy tools for the `Eth` gem for convenience. + # Defines handy tools for the {Eth} gem for convenience. module Util extend self @@ -92,7 +92,7 @@ def bin_to_prefixed_hex(bin) # Checks if a string is hex-adecimal. # # @param str [String] a string to be checked. - # @return [String] a match if true; nil if not. + # @return [String] a match if true; `nil` if not. def is_hex?(str) return false unless str.is_a? String str = remove_hex_prefix str @@ -102,7 +102,7 @@ def is_hex?(str) # Checks if a string is prefixed with `0x`. # # @param hex [String] a string to be checked. - # @return [String] a match if true; nil if not. + # @return [String] a match if true; `nil` if not. def is_prefixed?(hex) hex.match /\A0x/ end @@ -110,8 +110,8 @@ def is_prefixed?(hex) # Serializes an unsigned integer to big endian. # # @param num [Integer] unsigned integer to be serialized. - # return [String] serialized big endian integer string. - # raises [ArgumentError] if unsigned integer is out of bounds. + # @return [String] serialized big endian integer string. + # @raise [ArgumentError] if unsigned integer is out of bounds. def serialize_int_to_big_endian(num) num = num.to_i(16) if is_hex? num unless num.is_a? Integer and num >= 0 and num <= Constant::UINT_MAX @@ -123,7 +123,7 @@ def serialize_int_to_big_endian(num) # Converts an integer to big endian. # # @param num [Integer] integer to be converted. - # return [String] packed, big-endian integer string. + # @return [String] packed, big-endian integer string. def int_to_big_endian(num) hex = num.to_s(16) unless is_hex? num hex = "0#{hex}" if hex.size.odd? @@ -141,7 +141,7 @@ def deserialize_big_endian_to_int(str) # Converts a big endian to an interger. # # @param str [String] big endian to be converted. - # return [Integer] an unpacked integer number. + # @return [Integer] an unpacked integer number. def big_endian_to_int(str) str.unpack("H*").first.to_i(16) end @@ -149,7 +149,7 @@ def big_endian_to_int(str) # Converts a binary string to bytes. # # @param str [String] binary string to be converted. - # return [Object] the string bytes. + # @return [Object] the string bytes. def str_to_bytes(str) is_bytes?(str) ? str : str.b end @@ -157,7 +157,7 @@ def str_to_bytes(str) # Converts bytes to a binary string. # # @param bin [Object] bytes to be converted. - # return [String] a packed binary string. + # @return [String] a packed binary string. def bytes_to_str(bin) bin.unpack("U*").pack("U*") end diff --git a/lib/eth/version.rb b/lib/eth/version.rb index 1d3ab8af..dcd80989 100644 --- a/lib/eth/version.rb +++ b/lib/eth/version.rb @@ -12,9 +12,9 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Provides the `Eth` module. +# Provides the {Eth} module. module Eth - # Defines the version of the `Eth` module. + # Defines the version of the {Eth} module. VERSION = "0.5.1".freeze end diff --git a/spec/eth/chain_spec.rb b/spec/eth/chain_spec.rb index 53b3d45b..61ddecf6 100644 --- a/spec/eth/chain_spec.rb +++ b/spec/eth/chain_spec.rb @@ -25,6 +25,7 @@ expect(Chain::XDAI_ARBITRUM).to eq 200 expect(Chain::GOERLI_OPTIMISM).to eq 420 expect(Chain::RINKEBY_ARBITRUM).to eq 421611 + expect(Chain::SEPOLIA).to eq 11155111 # Chain IDs for selected private networks expect(Chain::PRIVATE_GETH).to eq 1337 diff --git a/spec/eth/constant_spec.rb b/spec/eth/constant_spec.rb index 7f4207a2..241b0ec7 100644 --- a/spec/eth/constant_spec.rb +++ b/spec/eth/constant_spec.rb @@ -15,8 +15,6 @@ expect(Constant::INT_MAX).to eq 57896044618658097711785492504343953926634992332820282019728792003956564819967 expect(Constant::INT_MIN).to eq -57896044618658097711785492504343953926634992332820282019728792003956564819968 expect(Constant::HASH_ZERO).to eq "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" - expect(Constant::PRIVKEY_ZERO).to eq "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" - expect(Constant::PRIVKEY_ZERO_HEX).to eq "0000000000000000000000000000000000000000000000000000000000000000" expect(Constant::SHORT_LENGTH_LIMIT).to eq 56 expect(Constant::LONG_LENGTH_LIMIT).to eq 18446744073709551616 expect(Constant::PRIMITIVE_PREFIX_OFFSET).to eq 128