abicoder 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23ce318ecd9bff53b9586cb30f15aac0f405991baae8ed3823fd8a1f1e357ca6
-  data.tar.gz: 4760a854236914e5d4fe42db0ced4f51bad4a7132fe14fe813f02af3f99043ca
+  metadata.gz: 3bc1e75e6080a55ae3447f7cfd3630ed587edf021658dd9159584fbb3ef28743
+  data.tar.gz: 84d27e90d278d0c2fc84db605005735164b4a63c084c087777218eadadb0044b
 SHA512:
-  metadata.gz: 82f6dfb3fb1f7eb2cb5352196d7a33476da85a684a93d72785ee37ca47af712f2864b46ddfbe6bc7bac76be3c0cb6f152620e0de9e883f8eaff44f12b57b9241
-  data.tar.gz: 3ca6cdc5aaabb5bfaa4c13aff8f5daaba0880e5b3c33e4ada1aa02053617a20e0681e27bf8f2a6451919d5233923c5ca69fe97a0bd4bafb3aa6cbbecf5405ee4
+  metadata.gz: 597f54c3c8e21027bb10d326c7c6763653d752ad3285abc1c2086023d17c6dc9207d8e99f16a008265bff3a2ad61e1f261db501911c46df56a509660102dc019
+  data.tar.gz: b776e32b5afd57e233aef6ffb87dba66b65272533f60f635c371e0a199fad593a1bd55cd6248f39a3002849b66e77ecf1bb7bd06f3ccc453cc87854d0c77d059

data/Manifest.txt

@@ -3,8 +3,8 @@ Manifest.txt
 README.md
 Rakefile
 lib/abicoder.rb
-lib/abicoder/codec.rb
-lib/abicoder/type.rb
-lib/abicoder/type_tuple.rb
-lib/abicoder/utils.rb
+lib/abicoder/decoder.rb
+lib/abicoder/encoder.rb
+lib/abicoder/parser.rb
+lib/abicoder/types.rb
 lib/abicoder/version.rb

data/README.md

@@ -13,6 +13,9 @@ abicoder - "lite" application binary interface (abi) encoding / decoding machine
 ## Usage
 
 
+###  Encode & Decode Types (Contract Function Call Data)
+
+
 ``` ruby
 require 'abicode'
 
@@ -20,38 +23,53 @@ require 'abicode'
 #  try ABI.encode
 
 ##  Encoding simple types
-ABI.encode( [ 'uint256', 'string' ],
-               [ 1234, 'Hello World' ]).hexdigest
-#=> "00000000000000000000000000000000000000000000000000000000000004d2"+
-#   "0000000000000000000000000000000000000000000000000000000000000040"+
-#   "000000000000000000000000000000000000000000000000000000000000000b"+
-#   "48656c6c6f20576f726c64000000000000000000000000000000000000000000"
+types = [ 'uint256', 'string' ]
+args  = [ 1234, 'Hello World' ]
+ABI.encode( types, args )   # returns binary blob / string
+#=> hex"00000000000000000000000000000000000000000000000000000000000004d2"+
+#      "0000000000000000000000000000000000000000000000000000000000000040"+
+#      "000000000000000000000000000000000000000000000000000000000000000b"+
+#      "48656c6c6f20576f726c64000000000000000000000000000000000000000000"
 
 ## Encoding with arrays types
-ABI.encode([ 'uint256[]', 'string' ],
-              [ [1234, 5678] , 'Hello World' ]).hexdigest
-#=> "0000000000000000000000000000000000000000000000000000000000000040"+
-#   "00000000000000000000000000000000000000000000000000000000000000a0"+
-#   "0000000000000000000000000000000000000000000000000000000000000002"+
-#   "00000000000000000000000000000000000000000000000000000000000004d2"+
-#   "000000000000000000000000000000000000000000000000000000000000162e"+
-#   "000000000000000000000000000000000000000000000000000000000000000b"+
-#   "48656c6c6f20576f726c64000000000000000000000000000000000000000000"
+types = [ 'uint256[]', 'string' ]
+args  = [ [1234, 5678] , 'Hello World' ]
+ABI.encode( types, args )    # returns binary blob / string
+#=> hex"0000000000000000000000000000000000000000000000000000000000000040"+
+#      "00000000000000000000000000000000000000000000000000000000000000a0"+
+#      "0000000000000000000000000000000000000000000000000000000000000002"+
+#      "00000000000000000000000000000000000000000000000000000000000004d2"+
+#      "000000000000000000000000000000000000000000000000000000000000162e"+
+#      "000000000000000000000000000000000000000000000000000000000000000b"+
+#      "48656c6c6f20576f726c64000000000000000000000000000000000000000000"
+
+## Encoding complex structs (also known as tuples)
+types = [ 'uint256', '(uint256,string)']
+args = [1234, [5678, 'Hello World']]
+ABI.encode( types, args )    # returns binary blob / string
+#=> hex'00000000000000000000000000000000000000000000000000000000000004d2'+
+#      '0000000000000000000000000000000000000000000000000000000000000040'+
+#      '000000000000000000000000000000000000000000000000000000000000162e'+
+#      '0000000000000000000000000000000000000000000000000000000000000040'+
+#      '000000000000000000000000000000000000000000000000000000000000000b'+
+#      '48656c6c6f20576f726c64000000000000000000000000000000000000000000'
 
 
 #####
 #  try ABI.decode
 
 ##  Decoding simple types
+types = [ 'uint256', 'string' ]
 data = hex'00000000000000000000000000000000000000000000000000000000000004d2'+
           '0000000000000000000000000000000000000000000000000000000000000040'+
           '000000000000000000000000000000000000000000000000000000000000000b'+
           '48656c6c6f20576f726c64000000000000000000000000000000000000000000'
-ABI.decode([ 'uint256', 'string' ], data)
+ABI.decode( types, data)   # returns args
 #=>  [1234, "Hello World"]
 
 
 ##  Decoding with arrays types
+types = [ 'uint256[]', 'string' ]
 data = hex'0000000000000000000000000000000000000000000000000000000000000040'+
           '00000000000000000000000000000000000000000000000000000000000000a0'+
           '0000000000000000000000000000000000000000000000000000000000000002'+
@@ -59,21 +77,72 @@ data = hex'0000000000000000000000000000000000000000000000000000000000000040'+
           '000000000000000000000000000000000000000000000000000000000000162e'+
           '000000000000000000000000000000000000000000000000000000000000000b'+
           '48656c6c6f20576f726c64000000000000000000000000000000000000000000'
-ABI.decode([ 'uint256[]', 'string' ], data )
+ABI.decode( types, data )   # returns args
 #=>  [[1234, 5678], "Hello World"]
 
 
 ## Decoding complex structs (also known as tuples)
+types = [ 'uint256', '(uint256,string)']
 data = hex'00000000000000000000000000000000000000000000000000000000000004d2'+
           '0000000000000000000000000000000000000000000000000000000000000040'+
           '000000000000000000000000000000000000000000000000000000000000162e'+
           '0000000000000000000000000000000000000000000000000000000000000040'+
           '000000000000000000000000000000000000000000000000000000000000000b'+
           '48656c6c6f20576f726c64000000000000000000000000000000000000000000'
-ABI.decode([ 'uint256', '(uint256,string)'], data)
+ABI.decode( types, data )   # returns args
 #=> [1234, [5678, "Hello World"]]
 ```
 
+and so on.
+
+
+
+
+
+## Reference
+
+For the full (and latest) official application
+binary inteface (abi) specification
+see the [**Contract ABI Specification**](https://docs.soliditylang.org/en/develop/abi-spec.html).
+
+
+### Types
+
+The following elementary types are supported:
+
+- `uint<M>`: unsigned integer type of `M` bits, `0 < M <= 256`, `M % 8 == 0`. e.g. `uint32`, `uint8`, `uint256`.
+- `int<M>`: two's complement signed integer type of `M` bits, `0 < M <= 256`, `M % 8 == 0`.
+- `address`: equivalent to `uint160`, except for the assumed interpretation and language typing.
+  For computing the function selector, `address` is used.
+- `bool`: equivalent to `uint8` restricted to the values 0 and 1. For computing the function selector, `bool` is used.
+- `bytes<M>`: binary type of `M` bytes, `0 < M <= 32`.
+
+
+The following (fixed-size) array types are supported:
+
+- `<type>[M]`: a fixed-length array of `M` elements, `M >= 0`, of the given type.
+
+<!--
+Note: While this ABI specification can express fixed-length arrays with zero elements,
+they're not supported by the compiler.
+-->
+
+The following non-fixed-size types are supported:
+
+- `bytes`: dynamic sized byte sequence.
+- `string`: dynamic sized unicode string assumed to be UTF-8 encoded.
+- `<type>[]`: a variable-length array of elements of the given type.
+
+Types can be combined to a tuple by enclosing them inside parentheses, separated by commas:
+
+- `(T1,T2,...,Tn)`: tuple consisting of the types `T1`, ..., `Tn`, `n >= 0`
+
+It is possible to form tuples of tuples, arrays of tuples and so on.
+
+<!--
+It is also possible to form zero-tuples (where `n == 0`).
+-->
+
 
 
 

data/lib/abicoder/decoder.rb

@@ -0,0 +1,208 @@
+module ABI
+
+
+class Decoder
+
+    ##
+    # Decodes multiple arguments using the head/tail mechanism.
+    #
+    def decode( types, data, raise_errors = false )
+      ## for convenience check if types is a String
+      ##   otherwise assume ABI::Type already
+      types = types.map { |type| type.is_a?( Type ) ? type : Type.parse( type ) }
+
+      outputs = [nil] * types.size
+      start_positions = [nil] * types.size + [data.size]
+
+      # TODO: refactor, a reverse iteration will be better
+      pos = 0
+      types.each_with_index do |t, i|
+        # If a type is static, grab the data directly, otherwise record its
+        # start position
+        if t.dynamic?
+
+          if pos>data.size-1
+            if raise_errors
+              raise DecodingError, "Position out of bounds #{pos}>#{data.size-1}"
+            else
+              puts "!! WARN - DecodingError: Position out of bounds #{pos}>#{data.size-1}"
+            end
+          end
+
+          start_positions[i] = big_endian_to_int(data[pos, 32])
+
+          if start_positions[i]>data.size-1
+            if raise_errors
+              raise DecodingError, "Start position out of bounds #{start_positions[i]}>#{data.size-1}"
+            else
+              puts "!! WARN - DecodingError: Start position out of bounds #{start_positions[i]}>#{data.size-1}"
+            end
+          end
+
+
+          j = i - 1
+          while j >= 0 && start_positions[j].nil?
+            start_positions[j] = start_positions[i]
+            j -= 1
+          end
+
+          pos += 32
+        else
+          ## puts "step 1 - decode item [#{i}] - #{t.format}  size: #{t.size} dynamic? #{t.dynamic?}"
+
+          outputs[i] = zero_padding( data, pos, t.size, start_positions )
+          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
+
+      if pos > data.size
+        if raise_errors
+          raise DecodingError, "Not enough data for head"
+        else
+          puts "!! WARN - DecodingError: Not enough data for head"
+        end
+      end
+
+
+      types.each_with_index do |t, i|
+        if t.dynamic?
+          offset, next_offset = start_positions[i, 2]
+          if offset<=data.size && next_offset<=data.size
+            outputs[i] = data[offset...next_offset]
+          end
+        end
+      end
+
+      if outputs.include?(nil)
+        if raise_errors
+          raise DecodingError, "Not all data can be parsed"
+        else
+          puts "!! WARN: DecodingError - Not all data can be parsed"
+        end
+      end
+
+
+      types.zip(outputs).map do |(t, out)|
+         ## puts "step 2 - decode item - #{t.format} got: #{out.size} byte(s) -  size: #{t.size} dynamic? #{t.dynamic?}"
+
+         decode_type(t, out)
+      end
+    end
+
+
+
+    def decode_type( type, arg )
+      return nil    if arg.nil? || arg.empty?
+
+
+      if type.is_a?( String ) || type.is_a?( Bytes )
+        l = big_endian_to_int( arg[0,32] )
+        data = arg[32..-1]
+        data[0, l]
+      elsif type.is_a?( Tuple )
+          arg ? decode(type.types, arg) : []
+      elsif type.is_a?( FixedArray )   # static-sized arrays
+        l       = type.dim
+        subtype = type.subtype
+        if subtype.dynamic?
+          start_positions = (0...l).map {|i| 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[subtype.size*i, subtype.size]) }
+        end
+      elsif type.is_a?( Array )
+        l = big_endian_to_int( arg[0,32] )
+        raise DecodingError, "Too long length: #{l}"  if l > 100000
+        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| 32+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
+      else
+        decode_primitive_type( type, arg )
+      end
+    end
+
+
+    def decode_primitive_type(type, data)
+      case type
+      when Address
+        encode_hex( data[12..-1] )
+      when String, Bytes
+          if data.length == 32
+            data[0..32]
+          else
+            size = big_endian_to_int( data[0,32] )
+            data[32..-1][0,size]
+          end
+      when FixedBytes
+          data[0, type.length]
+      when Uint
+        big_endian_to_int( data )
+      when Int
+        u = big_endian_to_int( data )
+        u >= 2**(type.bits-1) ? (u - 2**type.bits) : u
+      when Bool
+        data[-1] == BYTE_ONE
+      else
+        raise DecodingError, "Unknown primitive type: #{type.class.name} #{type.format}"
+      end
+    end
+
+
+    def zero_padding( data, pos, count, start_positions )
+      if pos >= data.size
+        start_positions[start_positions.size-1] += count
+        "\x00"*count
+      elsif pos + count > data.size
+        start_positions[start_positions.size-1] += ( count - (data.size-pos))
+        data[pos,data.size-pos] + "\x00"*( count - (data.size-pos))
+      else
+        data[pos, count]
+      end
+    end
+
+
+###########
+#  decoding helpers / utils
+
+def big_endian_to_int( bin )
+  bin = bin.sub( /\A(\x00)+/, '' )   ## keep "performance" shortcut - why? why not?
+  ### todo/check - allow nil - why? why not?
+  ##  raise DeserializationError, "Invalid serialization (not minimal length)" if !@size && serial.size > 0 && serial[0] == BYTE_ZERO
+  bin = bin || BYTE_ZERO
+  bin.unpack("H*").first.to_i(16)
+end
+
+def encode_hex( bin )   ## bin_to_hex
+  raise TypeError, "Value must be a String" unless bin.is_a?(::String)
+  bin.unpack("H*").first
+end
+
+
+end  # class Decoder
+
+end   ## module ABI

data/lib/abicoder/encoder.rb

@@ -0,0 +1,279 @@
+
+module ABI
+  ##
+  # Contract ABI encoding and decoding.
+  #
+  # @see https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI
+  #
+
+  class EncodingError < StandardError; end
+  class DecodingError < StandardError; end
+  class ValueError < StandardError; end
+
+  class ValueOutOfBounds < ValueError; end
+
+
+
+class Encoder
+
+    ##
+    # Encodes multiple arguments using the head/tail mechanism.
+    #
+    def encode( types, args )
+
+      ## todo/fix:  enforce args.size and types.size must match!!
+      ##   raise ArgumentError - expected x arguments got y!!!
+
+
+      ## for convenience check if types is a String
+      ##   otherwise assume ABI::Type already
+      types = types.map { |type| type.is_a?( Type ) ? type : Type.parse( type ) }
+
+      ## todo/check:  use args.map (instead of types)
+      ##                 might allow encoding less args than types?  - why? why not?
+      head_size = types
+                    .map {|type| type.size || 32 }
+                    .sum
+
+      head, tail = '', ''
+      types.each_with_index do |type, i|
+        if type.dynamic?
+          head += encode_uint256( head_size + tail.size )
+          tail += encode_type( type, args[i] )
+        else
+          head += encode_type( type, args[i] )
+        end
+      end
+
+      head + tail
+    end
+
+    ##
+    # Encodes a single value (static or dynamic).
+    #
+    # @param type [ABI::Type] value type
+    # @param arg [Object] value
+    #
+    # @return [String] encoded bytes
+    #
+    def encode_type( type, arg )
+      ## case 1)  string or bytes (note:are dynamic too!!! most go first)
+      ##  use type == Type.new( 'string', nil, [] ) - same as Type.new('string'))
+      ##   or type == Type.new( 'bytes', nil, [] )  - same as Type.new('bytes')
+      ##   - why? why not?
+      if type.is_a?( String )
+        encode_string( arg )
+      elsif type.is_a?( Bytes )
+         encode_bytes( arg )
+      elsif type.is_a?( Tuple )
+         encode_tuple( type, arg )
+      elsif type.is_a?( Array ) || type.is_a?( FixedArray )
+         if type.dynamic?
+           encode_dynamic_array( type, arg )
+         else
+           encode_static_array( type, arg )
+         end
+      else   # assume static (primitive) type
+         encode_primitive_type( type, arg )
+      end
+    end
+
+
+   def encode_dynamic_array( type, args )
+    raise ArgumentError, "arg must be an array" unless args.is_a?(::Array)
+
+        head, tail = '', ''
+
+        if type.is_a?( Array )  ## dynamic array
+          head += encode_uint256( args.size )
+        else  ## fixed array
+          raise ArgumentError, "Wrong array size: found #{args.size}, expecting #{type.dim}" unless args.size == type.dim
+        end
+
+        subtype = type.subtype
+        args.each do |arg|
+          if subtype.dynamic?
+            head += encode_uint256( 32*args.size + tail.size )
+            tail += encode_type( subtype, arg )
+          else
+            head += encode_type( subtype, arg )
+          end
+        end
+        head + tail
+   end
+
+
+   def encode_static_array( type, args )
+      raise ArgumentError, "arg must be an array" unless args.is_a?(::Array)
+      raise ArgumentError, "Wrong array size: found #{args.size}, expecting #{type.dim}" unless args.size == type.dim
+
+      args.map {|arg| encode_type( type.subtype, arg ) }.join
+   end
+
+
+   ##
+   ##  todo/check:  if static tuple gets encoded different
+   ##                   without offset  (head/tail)
+
+   def encode_tuple( tuple, args )
+    raise ArgumentError, "arg must be an array" unless args.is_a?(::Array)
+    raise ArgumentError, "Wrong array size (for tuple): found #{args.size}, expecting #{tuple.type.size} tuple elements" unless args.size == tuple.types.size
+
+       head_size =  tuple.types
+                     .map {|type| type.size || 32 }
+                     .sum
+
+        head, tail = '', ''
+        tuple.types.each_with_index do |type, i|
+          if type.dynamic?
+            head += encode_uint256( head_size + tail.size )
+            tail += encode_type( type, args[i] )
+          else
+            head += encode_type( type, args[i] )
+          end
+        end
+
+       head + tail
+   end
+
+
+
+    def encode_primitive_type( type, arg )
+      case type
+      when Uint
+        ## note: for now size in  bits always required
+        encode_uint( arg, type.bits )
+      when Int
+        ## note: for now size in  bits always required
+        encode_int( arg, type.bits )
+      when Bool
+        encode_bool( arg )
+      when String
+        encode_string( arg )
+      when FixedBytes
+        encode_bytes( arg, type.length )
+      when Bytes
+        encode_bytes( arg )
+      when Address
+        encode_address( arg )
+      else
+        raise EncodingError, "Unhandled type: #{type.class.name} #{type.format}"
+      end
+    end
+
+
+
+    def encode_bool( arg )
+      raise ArgumentError, "arg is not bool: #{arg}" unless arg.is_a?(TrueClass) || arg.is_a?(FalseClass)
+      lpad_int( arg ? 1 : 0 )
+    end
+
+
+    def encode_uint256( arg ) encode_uint( arg, 256 ); end
+    def encode_uint( arg, bits )
+      raise ArgumentError, "arg is not integer: #{arg}" unless arg.is_a?(Integer)
+      raise ValueOutOfBounds, arg   unless arg >= 0 && arg < 2**bits
+      lpad_int( arg )
+    end
+
+    def encode_int( arg, bits )
+      raise ArgumentError, "arg is not integer: #{arg}" unless arg.is_a?(Integer)
+      raise ValueOutOfBounds, arg   unless arg >= -2**(bits-1) && arg < 2**(bits-1)
+      lpad_int( arg % 2**bits )
+    end
+
+
+    def encode_string( arg )
+
+       ## todo/fix:  do NOT auto-unpack hexstring EVER!!!
+       ##                remove  arg.unpack('U*')
+
+      if arg.encoding == Encoding::UTF_8    ## was: name == 'UTF-8'
+        arg = arg.b
+      else
+        begin
+          arg.unpack('U*')
+        rescue ArgumentError
+          raise ValueError, "string must be UTF-8 encoded"
+        end
+      end
+
+      raise ValueOutOfBounds, "Integer invalid or out of range: #{arg.size}" if arg.size > UINT_MAX
+      size  =  lpad_int( arg.size )
+      value =  rpad( arg, ceil32(arg.size) )
+
+      size + value
+    end
+
+
+    def encode_bytes( arg, length=nil )
+      raise EncodingError, "Expecting string: #{arg}" unless arg.is_a?(::String)
+      arg = arg.b
+
+      if length # fixed length type
+        raise ValueOutOfBounds, "invalid bytes length #{length}" if arg.size > length
+        raise ValueOutOfBounds, "invalid bytes length #{length}" if length < 0 || length > 32
+        rpad( arg )
+      else  # variable length type  (if length is nil)
+        raise ValueOutOfBounds, "Integer invalid or out of range: #{arg.size}" if arg.size > UINT_MAX
+        size =  lpad_int( arg.size )
+        value = rpad( arg, ceil32(arg.size) )
+        size + value
+      end
+    end
+
+
+    def encode_address( arg )
+      if arg.is_a?( Integer )
+        lpad_int( arg )
+      elsif arg.size == 20
+        lpad( arg )
+      elsif arg.size == 40
+        lpad_hex( arg )
+      elsif arg.size == 42 && arg[0,2] == '0x'   ## todo/fix: allow 0X too - why? why not?
+        lpad_hex( arg[2..-1] )
+      else
+        raise EncodingError, "Could not parse address: #{arg}"
+      end
+    end
+
+
+###########
+#  encoding helpers / utils
+
+def rpad( bin, l=32, symbol=BYTE_ZERO )    ## note: same as builtin String#ljust !!!
+  return bin  if bin.size >= l
+  bin + symbol * (l - bin.size)
+end
+
+def lpad( bin, l=32, symbol=BYTE_ZERO )    ## note: same as builtin String#rjust !!!
+  return bin  if bin.size >= l
+  symbol * (l - bin.size) + bin
+end
+
+def lpad_int( n, l=32, symbol=BYTE_ZERO )
+  raise ArgumentError, "Integer invalid or out of range: #{n}" unless n.is_a?(Integer) && n >= 0 && n <= UINT_MAX
+  hex = n.to_s(16)
+  hex = "0#{hex}"   if hex.size.odd?
+  bin = [hex].pack("H*")
+
+  lpad( bin, l, symbol )
+end
+
+def lpad_hex( hex, l=32, symbol=BYTE_ZERO )
+  raise TypeError, "Value must be a string"  unless hex.is_a?( ::String )
+  raise TypeError, 'Non-hexadecimal digit found' unless hex =~ /\A[0-9a-fA-F]*\z/
+  bin = [hex].pack("H*")
+
+  lpad( bin, l, symbol )
+end
+
+
+
+def ceil32(x)
+  x % 32 == 0 ? x : (x + 32 - x%32)
+end
+
+end # class Encoder
+end  # module ABI
+