abicoder 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23ce318ecd9bff53b9586cb30f15aac0f405991baae8ed3823fd8a1f1e357ca6
-  data.tar.gz: 4760a854236914e5d4fe42db0ced4f51bad4a7132fe14fe813f02af3f99043ca
+  metadata.gz: f6aed5c766df24d4cf394f10fdaec00a7a42375cf85c5eab0a07d8f7f22ad3ec
+  data.tar.gz: 80c9a39735f1e383f168fdca5980d66acbf039a2bfbffe15866f0fb89a7090cf
 SHA512:
-  metadata.gz: 82f6dfb3fb1f7eb2cb5352196d7a33476da85a684a93d72785ee37ca47af712f2864b46ddfbe6bc7bac76be3c0cb6f152620e0de9e883f8eaff44f12b57b9241
-  data.tar.gz: 3ca6cdc5aaabb5bfaa4c13aff8f5daaba0880e5b3c33e4ada1aa02053617a20e0681e27bf8f2a6451919d5233923c5ca69fe97a0bd4bafb3aa6cbbecf5405ee4
+  metadata.gz: 9142a552978835f45a2be5bd80190905b9feeb519f135c8ae72f428826a2e7ccec467a1dbbfbfef8ddd2b097b1397f008429379230abc8ac6bcaf4aa53f7ec99
+  data.tar.gz: 37a0e2773d33a8c74881ccd8ab137e362dacde34c6dd076be0eed6ffe5b22f302ac8cdd2220e94ed124b5036a836b21b7977c0629daf9e749c45b2465e4aab47

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

@@ -1,6 +1,6 @@
 #  Application Binary Inteface (ABI) Coder For Ethereum & Co.
 
-abicoder - "lite" application binary interface (abi) encoding / decoding machinery / helper for Ethereum & Co. (blockchain) contracts with zero-dependencies for easy (re)use
+abicoder - "lite" application binary interface (abi) encoding / decoding machinery / helper (incl. nested arrays and/or tuples) for Ethereum & Co. (blockchain) contracts with zero-dependencies for easy (re)use
 
 
 * home  :: [github.com/rubycocos/blockchain](https://github.com/rubycocos/blockchain)
@@ -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/Rakefile

@@ -13,7 +13,7 @@ Hoe.spec 'abicoder' do
 
   self.version = ABICoder::VERSION
 
-  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.summary = "abicoder - 'lite' application binary interface (abi) encoding / decoding machinery / helper (incl. nested arrays and/or tuples) 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,207 @@
+module ABI
+
+
+class Decoder
+
+    ##
+    # Decodes multiple arguments using the head/tail mechanism.
+    #
+    def decode( types, data, raise_errors = false )
+       ##
+       ##  todo/check:  always change data (string) to binary encoding (e.g. data = data.b )
+       ##                    or such - why? why not?
+
+      ## 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 - why? why not?
+      #   try to simplify / clean-up code - possible? why? why not?
+
+      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] = decode_uint256(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?}"
+
+          count = t.size
+          ## was zero_padding( data, pos, t.size, start_positions )
+          ##   inline for now and clean-up later - why? why not?
+          outputs[i] = if pos >= data.size
+                          start_positions[start_positions.size-1] += count
+                          BYTE_ZERO*count
+                        elsif pos + count > data.size
+                          start_positions[start_positions.size-1] += ( count - (data.size-pos))
+                          data[pos,data.size-pos] + BYTE_ZERO*( count - (data.size-pos))
+                        else
+                          data[pos, count]
+                        end
+
+          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, data )
+      return nil    if data.nil? || data.empty?
+
+      if type.is_a?( Tuple )   ## todo: support empty (unit) tuple - why? why not?
+          decode( type.types, data )
+      elsif type.is_a?( FixedArray )   # static-sized arrays
+        l       = type.dim
+        subtype = type.subtype
+        if subtype.dynamic?
+          start_positions = (0...l).map {|i| decode_uint256(data[32*i, 32]) }
+          start_positions.push( data.size )
+
+          outputs = (0...l).map {|i| data[start_positions[i]...start_positions[i+1]] }
+
+          outputs.map {|out| decode_type(subtype, out) }
+        else
+          (0...l).map {|i| decode_type(subtype, data[subtype.size*i, subtype.size]) }
+        end
+      elsif type.is_a?( Array )
+        l = decode_uint256( data[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 data.size >= 32 + 32*l
+
+          start_positions = (1..l).map {|i| 32+decode_uint256(data[32*i, 32]) }
+          start_positions.push( data.size )
+
+          outputs = (0...l).map {|i| data[start_positions[i]...start_positions[i+1]] }
+
+          outputs.map {|out| decode_type(subtype, out) }
+        else
+          (0...l).map {|i| decode_type(subtype, data[32 + subtype.size*i, subtype.size]) }
+        end
+      else
+        decode_primitive_type( type, data )
+      end
+    end
+
+
+    def decode_primitive_type(type, data)
+      case type
+      when Uint
+        decode_uint256( data )
+      when Int
+        u = decode_uint256( data )
+        u >= 2**(type.bits-1) ? (u - 2**type.bits) : u
+      when Bool
+        data[-1] == BYTE_ONE
+      when String
+        ## note: convert to a string (with UTF_8 encoding NOT BINARY!!!)
+        size = decode_uint256( data[0,32] )
+        data[32..-1][0,size].force_encoding( Encoding::UTF_8 )
+      when Bytes
+        size = decode_uint256( data[0,32] )
+        data[32..-1][0,size]
+      when FixedBytes
+        data[0, type.length]
+      when Address
+        ## note: convert to a hex string (with UTF_8 encoding NOT BINARY!!!)
+        data[12..-1].unpack("H*").first.force_encoding( Encoding::UTF_8 )
+      else
+        raise DecodingError, "Unknown primitive type: #{type.class.name} #{type.format}"
+      end
+    end
+
+
+
+###########
+#  decoding helpers / utils
+
+def decode_uint256( 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
+
+
+
+end  # class Decoder
+
+end   ## module ABI

data/lib/abicoder/encoder.rb

@@ -0,0 +1,278 @@
+
+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.
+    #     returns binary string (with BINARY / ASCII_8BIT encoding)
+    #
+    def encode( types, args )
+      ## enforce args.size and types.size must match - why? why not?
+      raise ArgumentError, "Wrong number of args: found #{args.size}, expecting #{types.size}" unless args.size == types.size
+
+
+      ## 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 = ''.b, ''.b    ## note: use string buffer with BINARY / ASCII_8BIT encoding!!!
+      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 )
+      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 = ''.b, ''.b    ## note: use string buffer with BINARY / ASCII_8BIT encoding!!!
+
+        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 = ''.b, ''.b    ## note: use string buffer with BINARY / ASCII_8BIT encoding!!!
+        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 EncodingError or ArgumentError - why? why not?
+      raise ArgumentError, "arg is not bool: #{arg}" unless arg.is_a?(TrueClass) || arg.is_a?(FalseClass)
+      lpad( arg ? BYTE_ONE : BYTE_ZERO )   ## was  lpad_int( arg ? 1 : 0 )
+    end
+
+
+    def encode_uint256( arg ) encode_uint( arg, 256 ); end
+    def encode_uint( arg, bits )
+      ## raise EncodingError or ArgumentError - why? why not?
+      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 EncodingError or ArgumentError - why? why not?
+      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 )
+      ## raise EncodingError or ArgumentError - why? why not?
+      raise EncodingError, "Expecting string: #{arg}" unless arg.is_a?(::String)
+      arg = arg.b   if arg.encoding != Encoding::BINARY    ## was: name == 'UTF-8'
+
+      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 or ArgumentError - why? why not?
+      raise EncodingError, "Expecting string: #{arg}" unless arg.is_a?(::String)
+      arg = arg.b    if arg.encoding != Encoding::BINARY
+
+      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
+        ## note: make sure encoding is always binary!!!
+        arg = arg.b    if arg.encoding != Encoding::BINARY
+        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
+#    with "hard-coded" fill symbol as BYTE_ZERO
+
+def rpad( bin, l=32 )    ## note: same as builtin String#ljust !!!
+  # note: default l word is 32 bytes
+  return bin  if bin.size >= l
+  bin + BYTE_ZERO * (l - bin.size)
+end
+
+
+## rename to lpad32 or such - why? why not?
+def lpad( bin )    ## note: same as builtin String#rjust !!!
+  l=32   # note: default l word is 32 bytes
+  return bin  if bin.size >= l
+  BYTE_ZERO * (l - bin.size) + bin
+end
+
+## rename to lpad32_int or such - why? why not?
+def lpad_int( n )
+  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 )
+end
+
+## rename to lpad32_hex or such - why? why not?
+def lpad_hex( hex )
+  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 )
+end
+
+
+
+def ceil32(x)
+  x % 32 == 0 ? x : (x + 32 - x%32)
+end
+
+end # class Encoder
+end  # module ABI
+