web3-eth 0.1.0 → 0.2.0

data/README.md

@@ -1,7 +1,17 @@
 # Web3 RPC client for Ethereum node
 
 This Ruby Gem is used to connect and communicate with Ethereum node ( geth, parity, etc),
-having RPC interface. 
+having RPC interface. Also it has support to call Etherscan API.
+
+What you can do using this GEM:
+
+  - use Web3 eth interface methods to read blocks, transactions 
+  - query Etherscan to get ABI for validated contracts
+  - parse transaction method calls according to ABI
+  - parse transaction logs according to ABI
+  - parse contract creation arguments accroding to ABI
+  - list internal transaction using parity extended trace JSONRPC API
+
 
 ## Installation
 
@@ -21,6 +31,8 @@ Or install it yourself as:
 
 ## Usage
 
+### Connect
+
 Connecting to local node ( or by SSH Tunnel )
 
 ```ruby
@@ -32,10 +44,12 @@ To connect to remote Ethereum node, follow instructions: https://github.com/pari
 If you need to connect to remote host, you can specify host, port and HTTP connection options:
 
 ```ruby
-web3 = Web3::Eth::Rpc.new 'node.host.com', 8545, { use_ssl: true, read_timeout: 120 } 
+web3 = Web3::Eth::Rpc.new host: 'node.host.com', 
+                          port: 8545,  
+                          connect_options: { use_ssl: true, read_timeout: 120 } 
 ```
 
-Calling eth interface:
+### Calling eth interface
 
 ```
 >> web3.eth.blockNumber
@@ -62,6 +76,104 @@ Calling eth interface:
 ```
 
 
+### Calling Etherscan API:
+
+```
+api = Web3::Eth::Etherscan.new 'Your API Key'
+abi = api.contract_getabi address: '0xe3fedaecd47aa8eab6b23227b0ee56f092c967a9'
+```
+
+Method name for Etherscan must be constructed as <module>_<action>, for example contract_getabi 
+calls method getabi in module contract
+
+If method accepts only one parameter address, the call can be simplified to:
+
+```
+abi = api.contract_getabi '0xe3fedaecd47aa8eab6b23227b0ee56f092c967a9'
+```
+
+### Accesing contract methods
+
+```
+# creation of contract object
+myContract = web3.eth.contract(abi);
+
+# initiate contract for an address
+myContractInstance = myContract.at('0x2ad180cbaffbc97237f572148fc1b283b68d8861');
+
+# call constant function
+result = myContractInstance.balanceOf('0x...'); # any constant method works
+puts result 
+```
+
+or using Etherscan API ( requires contract ABI be published in Etherescan ):
+
+```
+api = Web3::Eth::Etherscan.new 'Your API Key'
+myContractInstance = web3.eth.load_contract(api, '0x2ad180cbaffbc97237f572148fc1b283b68d8861')
+
+// call constant function
+result = myContractInstance.balanceOf('0x....'); # any constant method works
+puts result // '0x25434534534'
+```
+
+
+### Parsing transaction call arguments
+
+Method parse_call_args parses call arguments according to ABI.
+Code example is:
+
+```
+api = Web3::Eth::Etherscan.new 'Your API Key'
+abi = api.contract_getabi address: '0x2ad180cbaffbc97237f572148fc1b283b68d8861'
+
+myContract = web3.eth.contract(abi);
+tx = web3.eth.getTransactionByHash '0x83da408b05061a2512fe1abf065b37a6aad9ae96d604b288a3da34bf9f1af9e6'
+myContract.parse_call_args tx
+```
+
+### Parsing smart contract constructor arguments
+
+Method parse_constructor_args parses smart contract creation arguments according to ABI.
+Code example is:
+
+```
+api = Web3::Eth::Etherscan.new 'Your API Key'
+abi = api.contract_getabi address: '0xf4702b0918a8a89dfc38459ce42198834818f26b'
+
+myContract = web3.eth.contract(abi);
+tx = web3.eth.getTransactionByHash '0x35f0cf1d1c7ec14dd40fe3949d1c535ec3f3953f118cb9dc1394370f966cf957'
+myContract.parse_constructor_args tx
+```
+
+### Parsing transaction logs
+
+Method parse_log_args parses indexed and not-indexed log event arguments according to ABI.
+Code example is:
+
+```
+api = Web3::Eth::Etherscan.new 'Your API Key'
+abi = api.contract_getabi address: '0x2ad180cbaffbc97237f572148fc1b283b68d8861'
+
+myContract = web3.eth.contract(abi);
+tx_receipt = web3.eth.getTransactionReceipt '0x83da408b05061a2512fe1abf065b37a6aad9ae96d604b288a3da34bf9f1af9e6'
+myContract.parse_log_args tx_receipt.logs.first
+```
+
+### Listing internal transactions
+
+To use this feature, you should run parity node with the option 
+--tracing on, refer to [https://github.com/paritytech/parity/wiki/Configuring-Parity#cli-options].
+
+```
+calls = web3.trace.internalCallsByHash '0x7ac18a1640e443cd069ff51da382b92b585e42dae8f38db0932380bfe86908a6'
+puts calls.first.from
+puts calls.first.to
+puts calls.first.value_eth
+```
+
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/web3/eth/abi/abi_coder.rb

@@ -0,0 +1,370 @@
+# -*- encoding : ascii-8bit -*-
+
+require 'web3/eth/abi/type'
+require 'web3/eth/abi/constant'
+require 'web3/eth/abi/exceptions'
+require 'web3/eth/abi/utils'
+
+module Web3::Eth::Abi
+
+  ##
+  # Contract ABI encoding and decoding.
+  #
+  # @see https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI
+  #
+  module AbiCoder
+
+    extend self
+
+    include Constant
+
+    class EncodingError < StandardError; end
+    class DecodingError < StandardError; end
+    class ValueOutOfBounds < ValueError; end
+
+    ##
+    # Encodes multiple arguments using the head/tail mechanism.
+    #
+    def encode_abi(types, args)
+      parsed_types = types.map {|t| Type.parse(t) }
+
+      head_size = (0...args.size)
+        .map {|i| parsed_types[i].size || 32 }
+        .reduce(0, &:+)
+
+      head, tail = '', ''
+      args.each_with_index do |arg, i|
+        if parsed_types[i].dynamic?
+          head += encode_type(Type.size_type, head_size + tail.size)
+          tail += encode_type(parsed_types[i], arg)
+        else
+          head += encode_type(parsed_types[i], arg)
+        end
+      end
+
+      "#{head}#{tail}"
+    end
+    alias :encode :encode_abi
+
+    ##
+    # Encodes a single value (static or dynamic).
+    #
+    # @param type [Ethereum::ABI::Type] value type
+    # @param arg [Object] value
+    #
+    # @return [String] encoded bytes
+    #
+    def encode_type(type, arg)
+      if %w(string bytes).include?(type.base) && type.sub.empty?
+        encode_primitive_type type, arg
+      elsif type.dynamic?
+        raise ArgumentError, "arg must be an array" unless arg.instance_of?(Array)
+
+        head, tail = '', ''
+        if type.dims.last == 0
+          head += encode_type(Type.size_type, arg.size)
+        else
+          raise ArgumentError, "Wrong array size: found #{arg.size}, expecting #{type.dims.last}" unless arg.size == type.dims.last
+        end
+
+        sub_type = type.subtype
+        sub_size = type.subtype.size
+        arg.size.times do |i|
+          if sub_size.nil?
+            head += encode_type(Type.size_type, 32*arg.size + tail.size)
+            tail += encode_type(sub_type, arg[i])
+          else
+            head += encode_type(sub_type, arg[i])
+          end
+        end
+
+        "#{head}#{tail}"
+      else # static type
+        if type.dims.empty?
+          encode_primitive_type type, arg
+        else
+          arg.map {|x| encode_type(type.subtype, x) }.join
+        end
+      end
+    end
+
+    def encode_primitive_type(type, arg)
+      case type.base
+      when 'uint'
+        begin
+          real_size = type.sub.to_i
+          i = get_uint arg
+
+          raise ValueOutOfBounds, arg unless i >= 0 && i < 2**real_size
+          Utils.zpad_int i
+        rescue EncodingError
+          raise ValueOutOfBounds, arg
+        end
+      when 'bool'
+        raise ArgumentError, "arg is not bool: #{arg}" unless arg.instance_of?(TrueClass) || arg.instance_of?(FalseClass)
+        Utils.zpad_int(arg ? 1 : 0)
+      when 'int'
+        begin
+          real_size = type.sub.to_i
+          i = get_int arg
+
+          raise ValueOutOfBounds, arg unless i >= -2**(real_size-1) && i < 2**(real_size-1)
+          Utils.zpad_int(i % 2**type.sub.to_i)
+        rescue EncodingError
+          raise ValueOutOfBounds, arg
+        end
+      when 'ufixed'
+        high, low = type.sub.split('x').map(&:to_i)
+
+        raise ValueOutOfBounds, arg unless arg >= 0 && arg < 2**high
+        Utils.zpad_int((arg * 2**low).to_i)
+      when 'fixed'
+        high, low = type.sub.split('x').map(&:to_i)
+
+        raise ValueOutOfBounds, arg unless arg >= -2**(high - 1) && arg < 2**(high - 1)
+
+        i = (arg * 2**low).to_i
+        Utils.zpad_int(i % 2**(high+low))
+      when 'string'
+        if arg.encoding.name == 'UTF-8'
+          arg = arg.b
+        else
+          begin
+            arg.unpack('U*')
+          rescue ArgumentError
+            raise ValueError, "string must be UTF-8 encoded"
+          end
+        end
+
+        if type.sub.empty? # variable length type
+          raise ValueOutOfBounds, "Integer invalid or out of range: #{arg.size}" if arg.size >= TT256
+          size = Utils.zpad_int arg.size
+          value = Utils.rpad arg, BYTE_ZERO, Utils.ceil32(arg.size)
+          "#{size}#{value}"
+        else # fixed length type
+          sub = type.sub.to_i
+          raise ValueOutOfBounds, "invalid string length #{sub}" if arg.size > sub
+          raise ValueOutOfBounds, "invalid string length #{sub}" if sub < 0 || sub > 32
+          Utils.rpad(arg, BYTE_ZERO, 32)
+        end
+      when 'bytes'
+        raise EncodingError, "Expecting string: #{arg}" unless arg.instance_of?(String)
+        arg = arg.b
+
+        if type.sub.empty? # variable length type
+          raise ValueOutOfBounds, "Integer invalid or out of range: #{arg.size}" if arg.size >= TT256
+          size = Utils.zpad_int arg.size
+          value = Utils.rpad arg, BYTE_ZERO, Utils.ceil32(arg.size)
+          "#{size}#{value}"
+        else # fixed length type
+          sub = type.sub.to_i
+          raise ValueOutOfBounds, "invalid bytes length #{sub}" if arg.size > sub
+          raise ValueOutOfBounds, "invalid bytes length #{sub}" if sub < 0 || sub > 32
+          Utils.rpad(arg, BYTE_ZERO, 32)
+        end
+      when 'hash'
+        size = type.sub.to_i
+        raise EncodingError, "too long: #{arg}" unless size > 0 && size <= 32
+
+        if arg.is_a?(Integer)
+          Utils.zpad_int(arg)
+        elsif arg.size == size
+          Utils.zpad arg, 32
+        elsif arg.size == size * 2
+          Utils.zpad_hex arg
+        else
+          raise EncodingError, "Could not parse hash: #{arg}"
+        end
+      when 'address'
+        if arg.is_a?(Integer)
+          Utils.zpad_int arg
+        elsif arg.size == 20
+          Utils.zpad arg, 32
+        elsif arg.size == 40
+          Utils.zpad_hex arg
+        elsif arg.size == 42 && arg[0,2] == '0x'
+          Utils.zpad_hex arg[2..-1]
+        else
+          raise EncodingError, "Could not parse address: #{arg}"
+        end
+      else
+        raise EncodingError, "Unhandled type: #{type.base} #{type.sub}"
+      end
+    end
+
+    ##
+    # Decodes multiple arguments using the head/tail mechanism.
+    #
+    def decode_abi(types, data)
+      parsed_types = types.map {|t| Type.parse(t) }
+
+      outputs = [nil] * types.size
+      start_positions = [nil] * types.size + [data.size]
+
+      # TODO: refactor, a reverse iteration will be better
+      pos = 0
+      parsed_types.each_with_index do |t, i|
+        # If a type is static, grab the data directly, otherwise record its
+        # start position
+        if t.dynamic?
+          start_positions[i] = Utils.big_endian_to_int(data[pos, 32])
+
+          j = i - 1
+          while j >= 0 && start_positions[j].nil?
+            start_positions[j] = start_positions[i]
+            j -= 1
+          end
+
+          pos += 32
+        else
+          outputs[i] = data[pos, t.size]
+          pos += t.size
+        end
+      end
+
+      # We add a start position equal to the length of the entire data for
+      # convenience.
+      j = types.size - 1
+      while j >= 0 && start_positions[j].nil?
+        start_positions[j] = start_positions[types.size]
+        j -= 1
+      end
+
+      raise DecodingError, "Not enough data for head" unless pos <= data.size
+
+      parsed_types.each_with_index do |t, i|
+        if t.dynamic?
+          offset, next_offset = start_positions[i, 2]
+          outputs[i] = data[offset...next_offset]
+        end
+      end
+
+      parsed_types.zip(outputs).map {|(type, out)| decode_type(type, out) }
+    end
+    alias :decode :decode_abi
+
+    def decode_type(type, arg)
+      if %w(string bytes).include?(type.base) && type.sub.empty?
+        l = Utils.big_endian_to_int arg[0,32]
+        data = arg[32..-1]
+
+        raise DecodingError, "Wrong data size for string/bytes object" unless data.size == Utils.ceil32(l)
+
+        data[0, l]
+      elsif type.dynamic?
+        l = Utils.big_endian_to_int arg[0,32]
+        subtype = type.subtype
+
+        if subtype.dynamic?
+          raise DecodingError, "Not enough data for head" unless arg.size >= 32 + 32*l
+
+          start_positions = (1..l).map {|i| Utils.big_endian_to_int arg[32*i, 32] }
+          start_positions.push arg.size
+
+          outputs = (0...l).map {|i| arg[start_positions[i]...start_positions[i+1]] }
+
+          outputs.map {|out| decode_type(subtype, out) }
+        else
+          (0...l).map {|i| decode_type(subtype, arg[32 + subtype.size*i, subtype.size]) }
+        end
+      elsif !type.dims.empty? # static-sized arrays
+        l = type.dims.last[0]
+        subtype = type.subtype
+
+        (0...l).map {|i| decode_type(subtype, arg[subtype.size*i, subtype.size]) }
+      else
+        decode_primitive_type type, arg
+      end
+    end
+
+    def decode_primitive_type(type, data)
+      case type.base
+      when 'address'
+        Utils.encode_hex data[12..-1]
+      when 'string', 'bytes'
+        if type.sub.empty? # dynamic
+          size = Utils.big_endian_to_int data[0,32]
+          data[32..-1][0,size]
+        else # fixed
+          data[0, type.sub.to_i]
+        end
+      when 'hash'
+        data[(32 - type.sub.to_i), type.sub.to_i]
+      when 'uint'
+        Utils.big_endian_to_int data
+      when 'int'
+        u = Utils.big_endian_to_int data
+        u >= 2**(type.sub.to_i-1) ? (u - 2**type.sub.to_i) : u
+      when 'ufixed'
+        high, low = type.sub.split('x').map(&:to_i)
+        Utils.big_endian_to_int(data) * 1.0 / 2**low
+      when 'fixed'
+        high, low = type.sub.split('x').map(&:to_i)
+        u = Utils.big_endian_to_int data
+        i = u >= 2**(high+low-1) ? (u - 2**(high+low)) : u
+        i * 1.0 / 2**low
+      when 'bool'
+        data[-1] == BYTE_ONE
+      else
+        raise DecodingError, "Unknown primitive type: #{type.base}"
+      end
+    end
+
+    private
+
+    def get_uint(n)
+      case n
+      when Integer
+        raise EncodingError, "Number out of range: #{n}" if n > UINT_MAX || n < UINT_MIN
+        n
+      when String
+        i = if n.size == 40
+              Utils.decode_hex(n)
+            elsif n.size <= 32
+              n
+            else
+              raise EncodingError, "String too long: #{n}"
+            end
+        i = Utils.big_endian_to_int i
+
+        raise EncodingError, "Number out of range: #{i}" if i > UINT_MAX || i < UINT_MIN
+        i
+      when true
+        1
+      when false, nil
+        0
+      else
+        raise EncodingError, "Cannot decode uint: #{n}"
+      end
+    end
+
+    def get_int(n)
+      case n
+      when Integer
+        raise EncodingError, "Number out of range: #{n}" if n > INT_MAX || n < INT_MIN
+        n
+      when String
+        i = if n.size == 40
+              Utils.decode_hex(n)
+            elsif n.size <= 32
+              n
+            else
+              raise EncodingError, "String too long: #{n}"
+            end
+        i = Utils.big_endian_to_int i
+
+        i = i > INT_MAX ? (i-TT256) : i
+        raise EncodingError, "Number out of range: #{i}" if i > INT_MAX || i < INT_MIN
+        i
+      when true
+        1
+      when false, nil
+        0
+      else
+        raise EncodingError, "Cannot decode int: #{n}"
+      end
+    end
+
+  end
+
+end

data/lib/web3/eth/abi/constant.rb

@@ -0,0 +1,30 @@
+# -*- encoding : ascii-8bit -*-
+
+module Web3::Eth::Abi
+  module Constant
+
+    BYTE_EMPTY = "".freeze
+    BYTE_ZERO  = "\x00".freeze
+    BYTE_ONE   = "\x01".freeze
+
+    TT32   = 2**32
+    TT40   = 2**40
+    TT160  = 2**160
+    TT256  = 2**256
+    TT64M1 = 2**64 - 1
+
+    UINT_MAX = 2**256 - 1
+    UINT_MIN = 0
+    INT_MAX  = 2**255 - 1
+    INT_MIN  = -2**255
+
+    HASH_ZERO = ("\x00"*32).freeze
+
+    PUBKEY_ZERO = ("\x00"*32).freeze
+    PRIVKEY_ZERO = ("\x00"*32).freeze
+    PRIVKEY_ZERO_HEX = ('0'*64).freeze
+
+    CONTRACT_CODE_SIZE_LIMIT = 0x6000
+
+  end
+end

data/lib/web3/eth/abi/exceptions.rb

@@ -0,0 +1,28 @@
+# -*- encoding : ascii-8bit -*-
+
+module Web3::Eth::Abi
+
+  class DeprecatedError < StandardError; end
+  class ChecksumError < StandardError; end
+  class FormatError < StandardError; end
+  class ValidationError < StandardError; end
+  class ValueError < StandardError; end
+  class AssertError < StandardError; end
+
+  class UnknownParentError < StandardError; end
+  class InvalidBlock < ValidationError; end
+  class InvalidUncles < ValidationError; end
+
+  class InvalidTransaction < ValidationError; end
+  class UnsignedTransactionError < InvalidTransaction; end
+  class InvalidNonce < InvalidTransaction; end
+  class InsufficientStartGas < InvalidTransaction; end
+  class InsufficientBalance < InvalidTransaction; end
+  class BlockGasLimitReached < InvalidTransaction; end
+
+  class InvalidSPVProof < ValidationError; end
+
+  class ContractCreationFailed < StandardError; end
+  class TransactionFailed < StandardError; end
+
+end

data/lib/web3/eth/abi/type.rb

@@ -0,0 +1,116 @@
+# -*- encoding : ascii-8bit -*-
+
+module Web3::Eth::Abi
+  class Type
+
+    class ParseError < StandardError;
+    end
+
+    class <<self
+      ##
+      # Crazy regexp to seperate out base type component (eg. uint), size (eg.
+      # 256, 128x128, nil), array component (eg. [], [45], nil)
+      #
+      def parse(type)
+        _, base, sub, dimension = /([a-z]*)([0-9]*x?[0-9]*)((\[[0-9]*\])*)/.match(type).to_a
+
+        dims = dimension.scan(/\[[0-9]*\]/)
+        raise ParseError, "Unknown characters found in array declaration" if dims.join != dimension
+
+        case base
+          when 'string'
+            raise ParseError, "String type must have no suffix or numerical suffix" unless sub.empty?
+          when 'bytes'
+            raise ParseError, "Maximum 32 bytes for fixed-length string or bytes" unless sub.empty? || sub.to_i <= 32
+          when 'uint', 'int'
+            raise ParseError, "Integer type must have numerical suffix" unless sub =~ /\A[0-9]+\z/
+
+            size = sub.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 'fixed', 'ufixed'
+            raise ParseError, "Fixed type must have suffix of form <high>x<low>, e.g. 128x128" unless sub =~ /\A[0-9]+x[0-9]+\z/
+
+            high, low = sub.split('x').map(&:to_i)
+            total = high + low
+
+            raise ParseError, "Fixed size out of bounds (max 32 bytes)" unless total >= 8 && total <= 256
+            raise ParseError, "Fixed high/low sizes must be multiples of 8" unless high % 8 == 0 && low % 8 == 0
+          when 'hash'
+            raise ParseError, "Hash type must have numerical suffix" unless sub =~ /\A[0-9]+\z/
+          when 'address'
+            raise ParseError, "Address cannot have suffix" unless sub.empty?
+          when 'bool'
+            raise ParseError, "Bool cannot have suffix" unless sub.empty?
+          else
+            raise ParseError, "Unrecognized type base: #{base}"
+        end
+
+        new(base, sub, dims.map {|x| x[1...-1].to_i})
+      end
+
+      def size_type
+        @size_type ||= new('uint', 256, [])
+      end
+    end
+
+    attr :base, :sub, :dims
+
+    ##
+    # @param base [String] base name of type, e.g. uint for uint256[4]
+    # @param sub  [String] subscript of type, e.g. 256 for uint256[4]
+    # @param dims [Array[Integer]] dimensions of array type, e.g. [1,2,0]
+    #   for uint256[1][2][], [] for non-array type
+    #
+    def initialize(base, sub, dims)
+      @base = base
+      @sub = sub
+      @dims = dims
+    end
+
+    def ==(another_type)
+      base == another_type.base &&
+          sub == another_type.sub &&
+          dims == another_type.dims
+    end
+
+    ##
+    # Get the static size of a type, or nil if dynamic.
+    #
+    # @return [Integer, NilClass]  size of static type, or nil for dynamic
+    #   type
+    #
+    def size
+      @size ||= if dims.empty?
+                  if %w(string bytes).include?(base) && sub.empty?
+                    nil
+                  else
+                    32
+                  end
+                else
+                  if dims.last == 0 # 0 for dynamic array []
+                    nil
+                  else
+                    subtype.dynamic? ? nil : dims.last * subtype.size
+                  end
+                end
+    end
+
+    def dynamic?
+      size.nil?
+    end
+
+    ##
+    # Type with one dimension lesser.
+    #
+    # @example
+    #   Type.parse("uint256[2][]").subtype # => Type.new('uint', 256, [2])
+    #
+    # @return [Ethereum::ABI::Type]
+    #
+    def subtype
+      @subtype ||= self.class.new(base, sub, dims[0...-1])
+    end
+
+  end
+end