abicoder 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45fa5adeeafa44036fa386f4ab36d3f822e5f91706423d578ea822e0d6fc01a8
-  data.tar.gz: 8430f2cdfeed351cee319596152b3c6d23ae506d6a51823ac909175df264eaff
+  metadata.gz: 3bc1e75e6080a55ae3447f7cfd3630ed587edf021658dd9159584fbb3ef28743
+  data.tar.gz: 84d27e90d278d0c2fc84db605005735164b4a63c084c087777218eadadb0044b
 SHA512:
-  metadata.gz: 4bb46c9aa7376a6d3ff7a0ed76b51c60b6068e9705ed8b7ce2980d89dc1a38e7331ffd3681e616264138d7f0d9819cf7981d4a26c323a7fef0ec42792c956c9e
-  data.tar.gz: 97ea5904ab15a98eea02f3a62d123c674bd34145828d04b93853dc615cf07031556143b6f51d4fa484a1b33479d26c7a6a1916acbb2df6dd503d4629e1dacac8
+  metadata.gz: 597f54c3c8e21027bb10d326c7c6763653d752ad3285abc1c2086023d17c6dc9207d8e99f16a008265bff3a2ad61e1f261db501911c46df56a509660102dc019
+  data.tar.gz: b776e32b5afd57e233aef6ffb87dba66b65272533f60f635c371e0a199fad593a1bd55cd6248f39a3002849b66e77ecf1bb7bd06f3ccc453cc87854d0c77d059

data/Manifest.txt

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

data/README.md

@@ -1,6 +1,6 @@
 #  Application Binary Inteface (ABI) Coder For Ethereum & Co.
 
-abicoder - application binary interface (abi) encoding / decoding machinery / helper for Ethereum & Co. (blockchain) contracts
+abicoder - "lite" application binary interface (abi) encoding / decoding machinery / helper for Ethereum & Co. (blockchain) contracts with zero-dependencies for easy (re)use
 
 
 * home  :: [github.com/rubycocos/blockchain](https://github.com/rubycocos/blockchain)
@@ -12,7 +12,136 @@ abicoder - application binary interface (abi) encoding / decoding machinery / he
 
 ## Usage
 
-To be done
+
+###  Encode & Decode Types (Contract Function Call Data)
+
+
+``` ruby
+require 'abicode'
+
+#####
+#  try ABI.encode
+
+##  Encoding simple types
+types = [ 'uint256', 'string' ]
+args  = [ 1234, 'Hello World' ]
+ABI.encode( types, args )   # returns binary blob / string
+#=> hex"00000000000000000000000000000000000000000000000000000000000004d2"+
+#      "0000000000000000000000000000000000000000000000000000000000000040"+
+#      "000000000000000000000000000000000000000000000000000000000000000b"+
+#      "48656c6c6f20576f726c64000000000000000000000000000000000000000000"
+
+## Encoding with arrays types
+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( types, data)   # returns args
+#=>  [1234, "Hello World"]
+
+
+##  Decoding with arrays types
+types = [ 'uint256[]', 'string' ]
+data = hex'0000000000000000000000000000000000000000000000000000000000000040'+
+          '00000000000000000000000000000000000000000000000000000000000000a0'+
+          '0000000000000000000000000000000000000000000000000000000000000002'+
+          '00000000000000000000000000000000000000000000000000000000000004d2'+
+          '000000000000000000000000000000000000000000000000000000000000162e'+
+          '000000000000000000000000000000000000000000000000000000000000000b'+
+          '48656c6c6f20576f726c64000000000000000000000000000000000000000000'
+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( 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/Rakefile

@@ -2,11 +2,18 @@ require 'hoe'
 require './lib/abicoder/version.rb'
 
 
+###
+# hack/ quick fix for broken intuit_values - overwrite with dummy
+class Hoe
+  def intuit_values( input ); end
+end
+
+
 Hoe.spec 'abicoder' do
 
   self.version = ABICoder::VERSION
 
-  self.summary = "abicoder - application binary interface (abi) encoding / decoding machinery / helper for Ethereum & Co. (blockchain) contracts"
+  self.summary = "abicoder - 'lite' application binary interface (abi) encoding / decoding machinery / helper for Ethereum & Co. (blockchain) contracts with zero-dependencies for easy (re)use"
   self.description = summary
 
   self.urls    = { home: 'https://github.com/rubycocos/blockchain' }

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
+

data/lib/abicoder/parser.rb

@@ -0,0 +1,158 @@
+module ABI
+class Type
+
+class ParseError < StandardError; end
+
+
+## nested inside Type - why? why not?
+class Parser
+
+   TUPLE_TYPE_RX = /^\((.*)\)
+                    ((\[[0-9]*\])*)
+                  /x
+
+  def self.parse( type )
+        if type =~ TUPLE_TYPE_RX
+             types   = _parse_tuple_type( $1 )
+             dims    = _parse_dims( $2 )
+
+             parsed_types = types.map{ |t| parse( t ) }
+
+             return _parse_array_type( Tuple.new( parsed_types ), dims )
+        end
+
+       base, sub, dims = _parse_base_type( type )
+
+       _validate_base_type( base, sub )
+
+       subtype =  case base
+                  when 'string'  then   String.new
+                  when 'bytes'   then   sub ? FixedBytes.new( sub ) : Bytes.new
+                  when 'uint'    then   Uint.new( sub )
+                  when 'int'     then   Int.new( sub )
+                  when 'address' then   Address.new
+                  when 'bool'    then   Bool.new
+                  else
+                    ## puts "  type: >#{type}<"
+                    raise ParseError, "Unrecognized type base: #{base}"
+                  end
+
+       _parse_array_type( subtype, dims )
+  end
+
+  ##
+  # Crazy regexp to seperate out base type component (eg. uint), size (eg.
+  # 256, 128, nil), array component (eg. [], [45], nil)
+  #
+  BASE_TYPE_RX = /([a-z]*)
+                  ([0-9]*)
+                  ((\[[0-9]*\])*)
+                 /x
+
+  def self._parse_base_type( str )
+    _, base, subscript, dimension = BASE_TYPE_RX.match( str ).to_a
+
+      ## note:  use [Integer,Integer] array in the future for sub
+      ##          for fixed  (e.g. 128x128 => [128,128]) or such
+      ##          for now always assume single integer (as string)
+    sub = subscript == '' ? nil : subscript.to_i
+
+    ## e.g. turn "[][1][2]" into [-1,1,2]
+    ##         or ""        into  []   -- that is, empty array
+    dims = _parse_dims( dimension )
+
+    [base, sub, dims]
+  end
+
+  def self._parse_dims( str )
+    dims = str.scan( /\[[0-9]*\]/ )
+
+    ## note: return -1 for dynamic array size e.g. []
+    ##        e.g. "[]"[1...-1]  => ""
+    ##             "[0]"[1...-1]  => "0"
+    ##             "[1]"[1...-1]  => "1"
+    dims = dims.map do |dim|
+                         size = dim[1...-1]
+                         size == '' ? -1 : size.to_i
+                    end
+    dims
+  end
+
+  def self._parse_array_type( subtype, dims )
+     ##
+     ## todo/check - double check if the order in reverse
+     ##                  in solidity / abi encoding / decoding?
+     ##
+    dims.each do |dim|
+      subtype = if dim == -1
+                     Array.new( subtype )
+                else
+                     FixedArray.new( subtype, dim )
+                end
+    end
+
+    subtype
+  end
+
+
+  def self._validate_base_type( base, sub )
+    case base
+    when 'string'
+      # note: string can not have any suffix
+      raise ParseError, "String cannot have suffix"  if sub
+    when 'bytes'
+      raise ParseError, "Maximum 32 bytes for fixed-length bytes"  if sub && sub > 32
+    when 'uint', 'int'
+      raise ParseError, "Integer type must have numerical suffix"  unless sub
+      raise ParseError, "Integer size out of bounds"    unless sub >= 8 && sub <= 256
+      raise ParseError, "Integer size must be multiple of 8"  unless sub % 8 == 0
+    when 'address'
+      raise ParseError, "Address cannot have suffix"  if sub
+    when 'bool'
+      raise ParseError, "Bool cannot have suffix"   if sub
+    else
+      ## puts "  type: >#{type}<"
+      raise ParseError, "Unrecognized type base: #{base}"
+    end
+  end
+
+
+
+    def self._parse_tuple_type( str )
+      ## note: types assumes string WITHOUT enclosing () e.g.
+      ##  tuple(string,string,bool)  =>  expected as "string,string,bool"
+
+      depth     = 0
+      collected = []
+      current   = ''
+
+      ### todo/fix: replace with a simple parser!!!
+      ##    allow  () and move verbose tuple() too!!!
+      str.each_char do |c|
+          case c
+          when ',' then
+            if depth == 0
+              collected << current
+              current = ''
+            else
+              current += c
+            end
+          when '(' then
+            depth += 1
+            current += c
+          when ')' then
+            depth -= 1
+            current += c
+          else
+            current += c
+          end
+      end
+      collected << current unless current.empty?
+
+      collected
+    end
+
+end # class Parser
+end  #  class Type
+end  # module ABI
+

data/lib/abicoder/types.rb

@@ -0,0 +1,155 @@
+module ABI
+
+
+#######
+## for now use (get inspired)
+##    by the type names used by abi coder in rust
+##      see  https://github.com/rust-ethereum/ethabi/blob/master/ethabi/src/param_type/param_type.rs
+
+
+class Type
+
+  def self.parse( type )   ## convenience helper
+    Parser.parse( type )
+  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
+    ## check/todo: what error to raise for not implemented / method not defined???
+    raise ArgumentError, "no required size method defined for Type subclass #{self.class.name}; sorry"
+  end
+  def dynamic?() size.nil?; end
+
+  def format
+    ## check/todo: what error to raise for not implemented / method not defined???
+    raise ArgumentError, "no required format method defined for Type subclass #{self.class.name}; sorry"
+  end
+
+  ####
+  ##   default implementation
+  ##    assume equal if class match (e.g. Address == Address)
+  ##    - use format string for generic compare - why? why not?
+end
+
+
+
+class Address < Type
+   def size() 32; end  ## note: address is always 20 bytes;  BUT uses 32 bytes (with padding)
+   def format() 'address'; end
+   def ==(another_type)  another_type.kind_of?( Address ); end
+end  # class Address
+
+class Bytes < Type
+   def size() nil; end    ## note: dynamic (not known at compile-time)
+   def format() 'bytes'; end
+   def ==(another_type)  another_type.kind_of?( Bytes ); end
+end  # class Bytes
+
+class FixedBytes < Type
+  attr_reader :length
+  def initialize( length )
+    @length = length   # in bytes (1,2,...32)
+  end
+  def size()  32; end   ## note: always uses 32 bytes (with padding)
+  def format() "bytes#{@length}"; end
+  def ==(another_type)
+     another_type.kind_of?( FixedBytes ) && @length == another_type.length
+  end
+end  # class FixedBytes
+
+class Int < Type
+   attr_reader :bits
+   def initialize( bits=256 )
+     @bits = bits  # in bits (8,16,...256)
+   end
+   def size() 32;  end   ## note: always uses 32 bytes (with padding)
+   def format() "int#{@bits}"; end
+   def ==(another_type)
+      another_type.kind_of?( Int ) && @bits == another_type.bits
+   end
+end  # class Int
+
+class  Uint < Type
+  attr_reader :bits
+  def initialize( bits=256 )
+    @bits = bits  # in bits (8,16,...256)
+  end
+  def size() 32;  end   ## note: always uses 32 bytes (with padding)
+  def format() "uint#{@bits}"; end
+  def ==(another_type)
+      another_type.kind_of?( Uint ) && @bits == another_type.bits
+  end
+end  # class  Uint
+
+class Bool < Type
+  def size() 32;  end   ## note: always uses 32 bytes (with padding)
+  def format() 'bool'; end
+  def ==(another_type)  another_type.kind_of?( Bool ); end
+end  # class Bool
+
+class String < Type
+  def size() nil; end    ## note: dynamic (not known at compile-time)
+  def format() 'string'; end
+  def ==(another_type)  another_type.kind_of?( String ); end
+end  # class String
+
+class Array < Type
+  attr_reader :subtype
+  def initialize( subtype )
+    @subtype = subtype
+  end
+  def size() nil; end    ## note: dynamic (not known at compile-time)
+  def format() "#{@subtype.format}[]"; end
+  def ==(another_type)
+    another_type.kind_of?( Array ) && @subtype == another_type.subtype
+  end
+end  # class Array
+
+class FixedArray < Type
+  attr_reader :subtype
+  attr_reader :dim
+  def initialize( subtype, dim )
+    @subtype = subtype
+    @dim      = dim
+  end
+
+  def size
+     @subtype.dynamic? ? nil : @dim * subtype.size
+  end
+  def format() "#{@subtype.format}[#{@dim}]"; end
+  def ==(another_type)
+      another_type.kind_of?( FixedArray ) &&
+        @dim == another_type.dim &&
+        @subtype == another_type.subtype
+  end
+end  # class FixedArray
+
+class Tuple < Type
+  attr_reader :types
+
+  def initialize( types )
+    @types = types
+  end
+
+  def size
+    s = 0
+    @types.each do |type|
+      ts = type.size
+      return nil   if ts.nil?
+      s += ts
+    end
+    s
+  end
+  def format
+    "(#{@types.map {|t| t.format }.join(',')})"  ## rebuild minimal string
+  end
+  def ==(another_type)
+    another_type.kind_of?( Tuple ) && @types == another_type.types
+  end
+end  # class Tuple
+end  # module ABI
+

data/lib/abicoder/version.rb

@@ -1,7 +1,7 @@
 
 module ABICoder
   MAJOR = 0
-  MINOR = 0
+  MINOR = 1
   PATCH = 1
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 

data/lib/abicoder.rb

@@ -4,13 +4,65 @@
 require_relative 'abicoder/version'    # note: let version always go first
 
 
-
 module ABI
+ ###################
+  ### some (shared) constants  (move to constants.rb or such - why? why not?)
+
+   ## todo/check:  use auto-freeze string literals magic comment - why? why not?
+   ##
+   ## todo/fix: move  BYTE_EMPTY, BYTE_ZERO, BYTE_ONE to upstream to bytes gem
+   ##    and make "global" constants - why? why not?
+
+   BYTE_EMPTY = "".b.freeze
+   BYTE_ZERO  = "\x00".b.freeze
+   BYTE_ONE   = "\x01".b.freeze      ## note: used for encoding bool for now
+
 
+   UINT_MAX = 2**256 - 1   ## same as 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
+   UINT_MIN = 0
+   INT_MAX  = 2**255 - 1   ## same as  57896044618658097711785492504343953926634992332820282019728792003956564819967
+   INT_MIN  = -2**255      ## same as -57896044618658097711785492504343953926634992332820282019728792003956564819968
 
 end  # module ABI
 
 
+require_relative 'abicoder/types'
+require_relative 'abicoder/parser'
+
+
+require_relative 'abicoder/encoder'
+require_relative 'abicoder/decoder'
+
+
+module ABI
+  def self.encoder
+    @encoder ||= Encoder.new
+  end
+  def self.decoder
+    @decoder ||= Decoder.new
+  end
+
+
+  def self.encode( types, args )
+      encoder.encode( types, args )
+  end
+
+  def self.decode( types, data, raise_errors = false )
+      decoder.decode( types, data, raise_errors )
+  end
+
+  ## add alternate _abi names  - why? why not?
+  class << self
+     alias_method :encode_abi, :encode
+     alias_method :decode_abi, :decode
+  end
+end    ## module ABI
+
+
+################
+## add convenience alternate spellings - why? why not?
+Abi = ABI
+
 
 
 puts ABICoder.banner   ## say hello

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abicoder
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-30 00:00:00.000000000 Z
+date: 2023-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -44,8 +44,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.23'
-description: abicoder - application binary interface (abi) encoding / decoding machinery
-  / helper for Ethereum & Co. (blockchain) contracts
+description: abicoder - 'lite' application binary interface (abi) encoding / decoding
+  machinery / helper for Ethereum & Co. (blockchain) contracts with zero-dependencies
+  for easy (re)use
 email: wwwmake@googlegroups.com
 executables: []
 extensions: []
@@ -59,6 +60,10 @@ files:
 - README.md
 - Rakefile
 - lib/abicoder.rb
+- lib/abicoder/decoder.rb
+- lib/abicoder/encoder.rb
+- lib/abicoder/parser.rb
+- lib/abicoder/types.rb
 - lib/abicoder/version.rb
 homepage: https://github.com/rubycocos/blockchain
 licenses:
@@ -84,6 +89,7 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: abicoder - application binary interface (abi) encoding / decoding machinery
-  / helper for Ethereum & Co. (blockchain) contracts
+summary: abicoder - 'lite' application binary interface (abi) encoding / decoding
+  machinery / helper for Ethereum & Co. (blockchain) contracts with zero-dependencies
+  for easy (re)use
 test_files: []