sbuilder-eth 0.0.4

data/lib/eth/sexp_utils.rb

@@ -0,0 +1,214 @@
+module Sbuilder
+  module Eth
+    # Utility to create SexpNodes
+    #
+    class SexpUtils
+
+      # ------------------------------------------------------------------
+      # @!group Id-generator
+
+      # @attr [Integer] idGenerator class variable used to generate
+      # unique identifiers
+      @@idGenerator = 1
+
+      ##
+      # @return [String] nextId unique indetifier generated for each call
+      def self.nextId
+        @@idGenerator += 1
+        "canonized-#{@@idGenerator}"
+      end
+      # @!endgroup
+
+      
+
+      # ------------------------------------------------------------------
+      # @!group YAML snippets
+
+      def self.strFunctionDefinition( name, inputs, outputs, block )
+        inputs = [ inputs ] if inputs.is_a? String
+        outputs = [ outputs ] if outputs.is_a? String        
+        <<~HERE
+        
+        id: #{nextId}
+        name: FunctionDefinition
+        src: '142:2:0'
+        attributes:
+          constant: true
+          implemented: true
+          isConstructor: false
+          modifiers:
+          - 
+          name: #{name}
+          payable: false
+          scope: 18
+          stateMutability: pure
+          superFunction: 
+          visibility: public
+        children:
+        #{children( [
+          strParameterList( inputs.map{ |i| strVariableDeclaration(i) }),
+          strParameterList( outputs.map{ |i| strVariableDeclaration(i) } ),
+          block,
+         ]
+         )}
+        HERE
+      end
+
+      def self.strBlock( statements = [])
+        statements = [ statements ] unless statements.is_a?( Array )
+        <<~HERE
+        id: #{nextId}
+        name: Block
+        src: '273:37:0'
+        children:
+        #{children(statements)}
+        HERE
+      end
+
+      def self.strIdentifer( identifierName )
+            <<~HERE
+            id: #{nextId}
+            name: Identifier
+            src: '290:11:0'
+            attributes: 
+                argumentTypes: 
+                overloadedDeclarations:
+                - 
+                referencedDeclaration: 3
+                type: uint256
+                value: #{identifierName}
+            HERE
+      end
+
+      def self.strReturnIdentifier( identifierName )
+        
+        <<~HERE
+        id: #{nextId}
+        name: Return
+        src: '283:18:0'
+        attributes: 
+            functionReturnParameters: 16
+        children:
+        #{children( [ strIdentifer( identifierName ) ])}
+        HERE
+
+      end
+            
+      def self.strParameterList( variables=[] )
+        variables = [ variables] if variables.is_a? String
+        <<~HERE
+        id: #{nextId}
+        name: ParameterList
+        src: '142:2:0'
+        attributes: 
+        children:
+        #{children(variables)}
+        HERE
+      end
+
+      # @return [String] YAML string mocking Solidity AST
+      #     VariableDeclation of 'variableName'
+      def self.strVariableDeclaration( variableName )
+        # Type should be of no interest because variable names are
+        # mapped to domains.
+        type ="uint256"
+        elementaryType="uint"
+        
+        variableStr=<<~EOS
+        name: VariableDeclaration
+        id: #{nextId}
+        attributes:
+          name: #{variableName}
+          type: #{type}
+        children:
+        - name: ElementaryTypeName
+          id: #{nextId}
+          attributes:
+            name: #{elementaryType}
+        EOS
+      end
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group Create AstSexps
+
+      # @return [AstSexp] Variaable declration for 'variableName'
+      def self.sexpVariableDeclaration( variableName )
+        AstSexp.from_hash(YAML.load(strVariableDeclaration( variableName )))
+      end
+
+      # Create :ParameterList sexp with parameters for 'variableNames'
+      #
+      # @param [Array<String>, String] variableNames
+      def self.sexpParameterList( variableNames=[] )
+        variableNames = [variableNames] if variableNames.is_a?(String)
+        AstSexp.from_hash(YAML.load(strParameterList( variableNames.map{ |v| strVariableDeclaration(v)} )))
+      end
+
+      # @!endgroup
+      
+
+      # ------------------------------------------------------------------
+      # @!group Services
+
+
+      # Create Getter method for 'variableName'
+      def self.sexpGetter( variableName )
+        AstSexp.from_hash(
+          YAML.load(
+          strFunctionDefinition(
+            getterName(variableName),
+            [], # no input
+            getterReturnVariableName(variableName),
+            strBlock( strReturnIdentifier( variableName ))
+          )
+        ))
+      end
+
+      def self.sexpReturnContact( sexpContract )
+      end
+
+
+
+      # @!endgroup
+
+
+      # ------------------------------------------------------------------
+      # @!group Helpers
+
+      # Embedd array 'arr' to YAML string.
+      #
+      # Implementation intends array 'arr' of String with first line
+      # prefixed '- ' and 2nd forward with ' '.
+      #
+      # @param arr [Array<String>] array of string lines
+      #
+      def self.children( arr )
+        arr.map do  |l|
+          first = true
+          l.gsub(/^(.*)/ ) do |line|
+            line = (first ? "- " + line : "  " + line )
+            first = false
+            line
+          end
+        end.join( "\n")
+      end
+
+      # @return [String] name of getter funcction of variable
+      #        'variableName '
+      def self.getterName( variableName )
+        "get#{ variableName[0].capitalize + variableName[1..-1] }"
+      end
+
+      def self.getterReturnVariableName(variableName)
+        "#{Constants::GETTER_RESPONSE_PREFIX}#{variableName}"
+      end
+
+      # @!endgroup
+
+
+
+    end
+  end
+end

data/lib/eth/solidity_compiler.rb

@@ -0,0 +1,145 @@
+require 'open3'
+
+
+module Sbuilder
+  module Eth
+
+    # Manage solidity compiler configuration {#solc_command},
+    # {#solc_flags}, {#output_directory} and provide method {#compile}
+    # to create AST for solidity source file.
+    # 
+    class SolidityCompiler
+
+      # @!attribute [String] solc_command 
+      attr_writer :solc_command
+
+      # @!attribute [String] solc_flags
+      attr_accessor :solc_flags
+
+      # @attribute [String] output_directory, can be configured outside
+      attr_accessor :output_directory
+
+      # @!group Constructor
+
+      def initialize( options={} )
+        initDefaults
+      end
+
+      def initDefaults
+        @output_directory = "cache/solidity"
+        @solc_flags   = " --overwrite  --combined-json ast" #  -o #{output_directory}
+        # @solc_command = "#{Dir.pwd}/solc/solidity/build/solc/solc"
+        @solc_command = ENV["SOLC"] || "#{Dir.pwd}/solc"
+      end
+      
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group Configuration accessors
+
+      def solc_command
+        @solc_command
+      end
+
+      
+      # @return [String] path to a file in output directory
+      # def ast_path( sourcePath )
+      #   "#{output_directory}/#{ast_file(sourcePath)}"
+      # end
+      
+      # @return [String] filename for abstract syntax tree for
+      # solidity source in +sourcePath+
+      # def ast_file( sourcePath )
+      #   "#{File.basename( sourcePath, File.extname(sourcePath) )}.sol_json.ast"
+      # end
+
+      # @!endgroup Compile
+
+      # ------------------------------------------------------------------
+      # @!group utilities
+
+      # @return [Boolean] true if +cmd+ points to executable or it is
+      # found in PATH
+      def which( cmd )
+        File.exists?( cmd ) && File.executable?( cmd ) ||
+          ENV['PATH'].split(':').select do |folder|
+          f = "#{folder}/#{cmd}"
+          File.exists?(f) && File.executable?(f)
+        end.any?
+      end
+
+      # @!endgroup      
+
+      # ------------------------------------------------------------------
+      # @!group Compile
+
+      # @param sourcePath [String] source path to sol file to compile
+      def compile( sourcePath, &blk )
+
+        # Check sourcePath & compiler command
+        # astPaths = cePaths.map do |sourcePath|
+        # @logger.info "#{__method__}: solc_command=#{solc_command}, solc_flags=#{solc_flags}, sourcePath=#{sourcePath}, pwd=#{Dir.pwd}"
+        raise CompilerException, "Solidity source file '#{sourcePath}': no such file" unless File.exists?( sourcePath )
+        # end
+        raise CompilerException, "Solidity output directory '#{output_directory}': no such directory" unless Dir.exists?( output_directory )        
+        raise CompilerException, "Solidity compiler '#{solc_command}': executable not found" unless which( solc_command )
+        
+
+        # ast named after first source file, must not exist
+        # astPath = ast_path( sourcePath )
+        # 
+        astPath = "#{output_directory}/combined.json"
+        
+        File.delete( astPath ) if File.exists?( astPath )
+        raise CompilerException, "Solidity ast file '#{astPath}': could not remove" if File.exists?( astPath )
+
+
+        # cmd = "#{solc_command} #{solc_flags} -o #{output_directory} #{sourcePath} > #{astPath}"
+        cmd = "#{solc_command} #{solc_flags} -o #{output_directory} #{sourcePath} > #{output_directory}/out.txt"        
+        # puts "cmd=#{cmd}"
+        out,err,exit_status = Open3.capture3( cmd )
+        
+        # logger.info "#{__method__}: out=#{out}, err=#{err}, st=#{exit_status}"
+        raise CompilerException, <<-EOS if exit_status != 0
+        Error in '#{cmd}'
+
+        exit status: #{exit_status}
+        stderr:  #{err}
+        output:  #{out}
+
+        When compiling solidity file  #{sourcePath} 
+        using compiler configuration:
+           solc_command: #{solc_command}
+           solc_flags: #{solc_flags}
+           output_directory: #{output_directory}
+
+
+        EOS
+        
+        # check that ast file was created
+        if ! File.exists?( astPath ) then
+          raise CompilerException, <<~EOS 
+          Error compiling #{sourcePath}
+
+          Compiler command
+
+          #{cmd}
+
+          in cwd #{Dir.getwd}
+
+          failed to create solidity ast file '#{astPath}'
+
+          EOS
+        end
+        
+        # logger.info "#{__method__}, compiledAst=#{compiledAst}"
+        yield astPath if block_given?
+        astPath
+      end
+        
+      # @!endgroup
+      
+    end # class SolidityCompiler
+  end
+end
+

data/lib/eth/solidity_loader.rb

@@ -0,0 +1,53 @@
+require 'json'
+
+module Sbuilder
+  module Eth
+    
+    class SolidityLoader
+      # ------------------------------------------------------------------
+      # @!group Constructor
+
+      def initialize(options={})
+      end
+      
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group Class services
+
+      
+
+      # @param [String] astPath path JSON file containing AST
+      # for several sourceUnits
+      #
+      # @yield sourceUnit, index, ast [String, Integer, AstSexp] if block given
+      #
+      # @return <Array<Array[String, int, AstSexp]> for solSource,
+      # index, AstTree
+      #
+
+      def load( astPath, &block )
+        # Read json form file
+        jsonStr = File.read( astPath )
+        raise "Empty json string from #{astPath}" if jsonStr.nil? || jsonStr.length == 0
+        solcHash = JSON.parse( jsonStr)
+        
+        # Iterate all sources in combined ast && convert to AstSexp structure
+        ret = 
+          solcHash["sourceList"].map.with_index do |solSource, index|
+          solAst = solcHash['sources'][solSource]['AST']
+          ast = AstSexp.from_hash( solAst )
+          yield solSource, index, ast if block_given?
+          # Builing array of arrays 
+          [solSource, index, ast ]
+        end
+        ret
+      end # def load( astPath, &block )
+
+      # @!endgroup
+      
+    end # class SolidityLoader
+  end
+end
+

data/lib/eth/solidity_translator.rb

@@ -0,0 +1,840 @@
+require "sbuilder-al"
+
+
+
+module Sbuilder
+  module Eth
+    class SolidityTranslator
+
+      # ------------------------------------------------------------------
+      # @!group Helper classes
+
+      # include logger
+      include Sbuilder::Al::Util::MyLogger         # mix logger
+
+      # @!endgroup
+
+
+      # ------------------------------------------------------------------
+      # @!group Attributes
+
+      # @!attribute [Hash] options options passed to initilization
+      attr_accessor :options
+      
+      # @!attribute [Sbuilder::Eth::Ethreum] ethApi the singleton Ethereum api inteface
+      attr_accessor :ethApi
+
+      # @!endgroup
+
+
+      # ------------------------------------------------------------------
+      # @!group Constructor
+
+      def initialize(options={})
+
+        self.options = options
+        @logger = getLogger( nil, options )
+        @logger.info( "#{__method__}: translator created")
+
+        initApi
+        
+      end
+
+      def initApi
+        self.ethApi = Ethereum.instance( options )
+      end
+
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group Class services
+
+      # @return [Array<AlObject>] Array of runtime objects, which
+      # should be added to only once. Particulary creates domain
+      # object 'codeHash', which includes values 'contracClasses'
+      #
+      # Assume that this method is called only once for ethereum
+      #
+      # @param contractClasses [Array<String>] array of knonw contract
+      #        classes defined
+      def solidityRuntime(contractClasses)
+        ethApi.ethRuntime  + [ ethApi.ethDomainCodeHash( contractClasses) ]
+      end
+
+
+      # For first time: return ethRuntime
+      #
+      # For each contract:
+      #
+      # - create contractType
+      # 
+      # @param ast [AstSexp] abstract syntax tree
+      #
+      # @param soliditySource [String] name of source file
+      #
+      # @param block [Block] block to yield name of contract translated 
+      #
+      # @return [Array<AlObject>] array of translated objects
+      def solidityTranslate( ast, soliditySource=nil, &block )
+
+        @logger.info "#{__method__}: soliditySource=#{soliditySource}"
+
+        # Run times object returned only once
+        alObjects = []
+        @logger.debug  "#{__method__}: alObjects=#{alObjects}" if @logger.debug?
+
+        if ( ast ) then
+
+          @logger.info "#{__method__}: ast:#{ast.sexp_type}, name=#{ast.attribute('name')}"
+          # valid input
+          alObjects = 
+            ast.nodes_with_match(:ContractDefinition).reduce( alObjects ) do |memo,contractAst|
+
+            # Let caller to know classes translated
+            yield contractAst['name'] if block_given?
+
+            # Load 'contractMappingTypes' before 'contractType' to
+            # create type defines before they are refenced
+            memo += contractMappingTypes(contractAst)            
+            memo += contractType(contractAst)
+            memo += contracFunctions(contractAst, soliditySource)          
+
+          end
+        end
+        alObjects
+      end
+
+      # @return [Hash] metaDefs (metatype definition) used by AlObject
+      # created in {#solidityTranslate}
+      #
+      # Implementation retrives 'metaDefs' from {#ethApi} Ethreum api
+      # inferface (used to create alObject in {#solidityTranslate})
+      def metaDefs
+        ethApi.ethMetaDefs
+      end
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group tranlate steops
+
+      # @param soliditySource [String] name of source file for contract implementantion 
+      #
+      # @return [Array<AlObject>] AL object array modeling Solitiy
+      # contract functions as 1) function entry, 2) function (as a
+      # transaction) implementation 3) function exit
+      def contracFunctions(contractAst, soliditySource)
+
+        alObjects = 
+          contractAst.nodes_with_match(:FunctionDefinition).reduce( [] ) do |memo,functionAst|
+          memo += [ functionEntry(contractAst, functionAst) ]
+          memo += functionImplementation( contractAst, functionAst, soliditySource )
+          memo += [functionExit(contractAst, functionAst)]
+        end || []
+        alObjects
+      end
+
+      # @return [AlObject] AL snippet to implement start of
+      # transaction (= entry to a function 'functionAst' in Solidity
+      # contract 'contractAst')
+      def functionEntry(contractAst, functionAst)
+        ethApi.ethServiceEntry( contractAst['name'], functionAst['name'] )
+      end
+
+      # @return [AlObject] AL snippet implemeting service exit
+      # (=completion of transaction for a function 'functionAst' in
+      # Solidity contract 'contractAst')
+      def functionExit(contractAst, functionAst)
+        ethApi.ethServiceExit( contractAst['name'], functionAst['name'] )          
+      end
+      
+      # @return [Array<AlObject>] AL object array for implementing
+      # function 'functionAst' in Solidity contract 'contractAst'.
+      #
+      # @param functionAst [AstSexp:FunctionDefinition] ast of
+      #        function to implement
+      #
+      def functionImplementation(contractAst, functionAst, soliditySource )
+        @logger.debug "#{__method__}: functionAst=#{functionAst}" if @logger.debug?
+        @logger.info "#{__method__}: soliditySource=#{soliditySource}, functionAst.sexp_type=#{functionAst.sexp_type}"
+
+        # lambda visit req(pos=0)/resp (pos=1) parameters (and types)
+        lParameters = lambda do |fAst, pos|
+          fAst.children { |c| c.sexp_type == :ParameterList || c.sexp_type == :ResponseParameterList }[pos].parameters.map{ |declAst| ethApi.ethVariableDeclaration(declAst) }
+        end
+
+
+        sourceLink = soliditySource.nil? ? nil : {
+          :sourceModule => soliditySource,
+          :sourceLine => functionAst['sourceLine'],
+        }
+        
+        [
+          ethApi.ethTransaction( contractAst.attribute('name'),    # contract name
+                                 functionAst.attribute("name"),    # function name --> operation
+                                 requestParameters: lParameters.curry[functionAst,0],
+                                 responseParameters: lParameters.curry[functionAst,1],
+                                 sourceLink: sourceLink
+                               ) do |txBlock|
+
+            #if contractAst.attribute('name') == functionAst.attribute("name")
+            if ethApi.isConstructor( contractAst.attribute('name'),  functionAst.attribute("name"))
+              # constructor
+              dispatchContractCreationPreamble( txBlock, contractAst,  functionAst)
+            else
+              # normal function
+              dispatchMessageCallPreamble( txBlock, contractAst,  functionAst)              
+            end
+
+            # add common actions before actually executing block stmts
+            dispatchCommonPreambe( txBlock, contractAst, functionAst )
+            
+            # Set 'invocationCtx' on :ModifierDefinition for
+            # :ModifierInvocation
+            functionAst.modifierInvocations.each do |modifierInvocation|
+              @logger.debug "#{__method__}: modifierInvocation=#{modifierInvocation}" if @logger.debug?
+
+              # 'msg' points to request parameters of 'functionAst' being translated
+              initInvocationCtx = { Constants::SOL_MSG => functionAst }
+
+              # create 'invocationCtx' with evaluted args of 'modifierInvocation' 
+              invocationCtx = modifierInvocation.arguments.reduce( initInvocationCtx ) do |ctx,arg|
+
+                # Formal parameter in :ModifierDefinition by position
+                # (exclude initInvocationCtx params)
+                parameterPos = ctx.keys.length - initInvocationCtx.keys.length
+                modifierFormalParameter = modifierInvocation.modifierDefinition.requestParameters.parameterByIndex( parameterPos )
+                @logger.info "#{__method__}: modifierInvocation=#{modifierInvocation.modifierDefinition['name']}, param #{ctx.keys.length}=#{modifierFormalParameter['name']}"
+
+                # arg translation  to tlaExpression
+                translatedArg = ethApi.dispatchExpression( arg )
+                @logger.debug "#{__method__}: modifierInvocation=#{modifierInvocation.modifierDefinition['name']}, param #{ctx.keys.length}=#{modifierFormalParameter}--> #{translatedArg.strOutput}" if @logger.debug?
+                # Build ctx hash
+                ctx[modifierFormalParameter["name"]] = translatedArg
+                ctx
+              end
+              
+              @logger.debug "#{__method__} using invocationCtx=#{invocationCtx}" if @logger.debug?
+              modifierInvocation.modifierDefinition.invocationCtx = invocationCtx
+
+              # expand preambleStatements (=staements upto _ -char)
+              modifierInvocation.modifierDefinition.preambleStatements.each do |stmtAst|
+                dispatchBlockStatement( txBlock, stmtAst, contractAst, functionAst )
+              end
+
+              # 'invocationCtx', valid only for during dispatchBlockStatement
+              modifierInvocation.modifierDefinition.invocationCtx = nil
+              
+            end # process modifiers
+
+            # process statements for :Block of :FunctionDefinition
+            functionAst.statements.each do |stmtAst|
+              dispatchBlockStatement( txBlock, stmtAst, contractAst, functionAst )
+            end
+            
+            # successfull return here
+            ethApi.ethActionFinalReturn( txBlock, contractAst["name"], functionAst["name"]  )
+            
+          end # ethTransaction
+        ]        
+      end
+
+
+      # Create function 'Al::FunctionDefinition' for each :Mapping
+      # contract member variable for mapping 'from' 'to'
+      def contractMappingTypes( contractAst )
+
+        # Create 'ehContractMappingFunction' for all ':Mapping' member variables
+        alObjects = contractAst.memberVariables.
+                    select { |variableAst| variableAst.variableType.sexp_type == :Mapping }.
+                    map { |variableAst| ethApi.ethContractMappingFunction( contractAst, variableAst) } ||
+                    []
+              
+        alObjects          
+      end
+
+      # Create 'AL::Definion' for contract 'contractAst'.
+      #
+      # For each 'memberVariable' the type definition  add either
+      #
+      # * parameter  - for :ElementaryTypeName
+      #
+      # * reference - for :Mapping and ::UserDefinedTypeName (for contracts)
+      #               pointing to type definition created separately
+      #
+      # @return [Array<AlObject>] 'ethContractType' for 'contractAst',
+      #          allow several, creates just one
+      #
+      # TODO: add support structs, enums, arrays
+      def contractType( contractAst )
+        @logger.debug "#{__method__}: ast=#{contractAst}" if @logger.debug?
+        @logger.info "#{__method__}: contract.name=#{contractAst.attribute('name')}"
+
+        alObjects = []
+        alObjects <<
+          ethApi.ethContractType( contractAst[ "name"] ) do |contractTypeDefinition|
+
+          # for each :VariableDeclation (direct childer of 'contractAst'
+          contractAst.memberVariables.each do |variableAst|
+            @logger.debug "#{__method__}: variableAst=#{variableAst}" if @logger.debug?
+            @logger.info "#{__method__}: variable.name=#{variableAst.attribute('name')}@#{contractAst[ 'name']}"
+
+            # Default non-array declaraion
+            variableType = variableAst.variableType 
+            isArray = false
+
+
+            # 
+            if variableType.sexp_type == :ArrayTypeName
+              isArray = true
+              # Array s(:VariableDeclaration, s(:ArrayTypeName,s(?variableType) ))
+              variableType = variableType.children[0]
+            end
+
+            case variableType.sexp_type
+            when :ElementaryTypeName
+              contractTypeDefinition.parameter( variableAst["name"], isArray )
+            when :UserDefinedTypeName
+              isArray = false
+              contractTypeDefinition.reference( variableAst["name"], isArray, variableType.reference["name"] )
+            when :Mapping
+              isArray = false
+              contractTypeDefinition.reference(
+                variableAst.attribute("name"), isArray,
+                ethApi.nContractMappingMemberDefinition( contractAst['name'], variableAst['name'] ) )
+            else
+              raise TranslatorException, "Implemenation for state variable type '#{variableAst.variableType.sexp_type}' not supported #{variableAst}"
+            end # case 
+          end # 
+        end # alObject create
+        
+      end # def contractType( contractAst )
+
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group Block pre/post -ables
+
+      # Actions starting transaction for running constructor
+      # 'functionAst' of contract 'contractAst'.
+      #
+      # Actions:
+      #  - init return response
+      #  - choose free id 'NextId' from the pool of free address
+      #    in tla state variable 'eth_addressPool'
+      #  - create new record for 'contractAst' account 'eth_accounts'
+      #  - create new record member variables in contract 'contractAst' into
+      #    'eth_storageRoot'
+      #  - save the identifier of constructed contracto to a local
+      #    variable 'thisCid' 
+      #  - create a labeled step 'start' to transaction procedure
+      #    to avoid clashes if traction statements make assignments
+      #    to tla variables modified in this preamble.
+      #
+      # @param blockBuilder [Al::BlockBuilder] block for actions
+      #        implementing constructor
+      #
+      # @param contractAst [AstSexp] contract to construct
+      #
+      # @param functionAst [AstSexp] ast of contract constructor
+      # 
+
+      def dispatchContractCreationPreamble( blockBuilder, contractAst, functionAst)
+
+        # Init return response 
+        ethApi.ethActioInitReturnValue( blockBuilder, contractAst, functionAst )
+        
+        # accounts := [ address |-> NextId, balance |-> 0, codeHash |->  ]
+        ethApi.ethActionNewAddress( blockBuilder, contractAst )
+
+        # storageRoot := [ address |-> NextId, f1 |-> ... ]
+        ethApi.ethActionNewStorageRoot( blockBuilder, contractAst )
+
+        # thisCid := NextId
+        ethApi.ethActionInitThis( blockBuilder, ethApi.ethNextId )
+
+        # NB: must the last because nextId changed
+        # addressPool := addrepress  \ NextId
+        ethApi.ethActionConsumeAddress( blockBuilder )
+
+        # Add label (=skip w. label) after preamble
+        blockBuilder.label( "start" )
+        
+      end
+
+      # Add AL preamble to block 'txBlock' for message call
+      # (=non-constructor) function 'functionAst' in contract
+      # 'contractAst'
+      #
+      #  * init response return 
+      # 
+      #  * set thisCid (local variable) to point 'msg.recipient'
+      #    (from  procedure input variable record field recipientl)
+      #
+      # @param blockBuilder [Al::BlockBuilder] block for actions
+      #        implementing constructor
+      #
+      # @param contractAst [AstSexp] contract to construct
+      #
+      # @param functionAst [AstSexp] ast of contract constructor
+      #
+      def dispatchMessageCallPreamble( blockBuilder, contractAst, functionAst)
+
+        # Init response return 
+        ethApi.ethActioInitReturnValue( blockBuilder, contractAst, functionAst )
+        
+        # thisCid := msg.recipint
+        ethApi.ethActionInitThis(
+          blockBuilder,
+          ethApi.ethMsgRecipient(contractAst["name"], functionAst["name"])
+        )
+
+        # Add label (=skip w. label) after preamble
+        blockBuilder.label( "start" )
+        
+      end
+
+      # Add common actions before actually executing tx
+      #
+      # Actions:
+      # 
+      # - ethActionCheckContractExists: create empty account and move
+      #     value if account 'thisCid' does not exist (possible for
+      #     message call, assume that constructor has created new
+      #     account pointed by thisCid )
+      #
+      # - ethActionCheckContractType: failure if account codeHash is
+      # - in-correct
+      #
+      # - ethActionMovevalue: move msg.value from msg.sender to 'thisCid'
+      #
+      # @param blockBuilder [Al::BlockBuilder] block for actions
+      #        implementing constructor
+      #
+      # @param contractAst [AstSexp] contract to construct
+      #
+      # @param functionAst [AstSexp] ast of contract constructor
+      # 
+      def dispatchCommonPreambe( blockBuilder, contractAst, functionAst)
+                
+        # Create empty account and exit for non existing account
+        ethApi.ethActionCheckContractExists( blockBuilder, contractAst, functionAst)
+
+        # Abort if codeHash does not match currencly executing contract
+        ethApi.ethActionCheckContractType( blockBuilder, contractAst, functionAst)
+
+        # Move value from sender to recipient
+        ethApi.ethActionMovevalue( blockBuilder, contractAst, functionAst)
+        
+      end
+      
+      # @!endgroup
+
+      # ------------------------------------------------------------------
+      # @!group description Block statements
+
+      
+      # Dispatch translation for 'stmtAst' in block for function
+      # 'functionAst' in contract 'functionAst'. Statements actions
+      # are added to block 'blockBuilder'
+      #
+      # @param blockBuilder [AL:BlockBuilder] AL block where statement should be added
+      #
+      # @param stmtAst [SexpA] statement to dispatch
+      #
+      # @param contractAst [SexpAst] contract of 'functionAst'
+      #
+      # @param functionAst [SexpAst] function of block where statement
+      #        belongs to
+      #
+      # TODO: add support for statements: switch, while, for, break,
+      # continue, ternary if. Document if some of these statements are
+      # handled by preprocessing.
+      #
+      # TODO: add support for revert and throw (from version 0.4.13
+      # the throw keyword is deprecated)
+      #
+      # TODO: add support for (internal and external )function calls.
+      #
+      # TODO: add support for named function call arguments (or add
+      # comment if handled by preprocesor)
+      #
+      # TODO: add suppport for calling constructor new keyword
+      
+      
+      def dispatchBlockStatement( blockBuilder, stmtAst, contractAst, functionAst )
+        @logger.debug( "#{__method__}: stmtAst=#{stmtAst}") if @logger.debug?
+        @logger.info "#{__method__} dispatch stmt: #{stmtAst.sexp_type} within #{contractAst['name']}(#{functionAst['name']})"
+
+        case stmtAst.sexp_type
+        when :Return
+          returnStatement( blockBuilder, stmtAst, contractAst, functionAst )
+        when :ExpressionStatement
+          exprStmt = stmtAst.children[0]
+          case exprStmt.sexp_type
+          when :Assignment
+            assignStatement( blockBuilder, exprStmt )
+          when :FunctionCall
+            dispatchFunctionCallStmt( blockBuilder, exprStmt, contractAst, functionAst )
+          else
+            raise TranslatorException,
+                  "Implemenation for 'ExpressionStatement'  missing for statement type '#{exprStmt.sexp_type}' in #{exprStmt}"            
+          end
+        when :FunctionCall
+          # Function call inserted for expression calls
+          dispatchFunctionCallStmt( blockBuilder, stmtAst, contractAst, functionAst )
+        when :IfStatement
+          ifStatement( blockBuilder, stmtAst, contractAst, functionAst )
+        when :Throw
+          throwStatement( blockBuilder, stmtAst, contractAst, functionAst )
+        else
+          raise TranslatorException, "Implemenation missing for statement type '#{stmtAst.sexp_type}' in #{stmtAst}"
+        end
+      end
+
+      # Distpatch traslation of :FunctionCall -statement. Call to
+      # Ethereum infrastructure services (=functions flagged as
+      # :reservedFunctionType) are processed separately.
+      #
+      #  - SelfDestruct --> {#SelfDestruct}
+      #  - Revert --> {#throwStatement}: alias for throw
+      #
+      # TODO: add support for suicide/kill (or document why not
+      # supported)
+      #
+      # TODO: add support for "normal function calls" (eiher running locally,
+      # or running in transaction.
+      #
+      def dispatchFunctionCallStmt( blockBuilder, functionCallStmt, contractAst, functionAst )
+        @logger.debug( "#{__method__}: functionCallStmt=#{functionCallStmt}") if @logger.debug?
+
+        # Dispatch well known Solidity functions ':reservedFunctionType'
+        dispatchSolidityFunctions = {
+          :SelfDestruct => ->( callStmt ) do
+            selfdestructStmt( blockBuilder, callStmt, contractAst, functionAst )
+          end,
+          :Revert => ->(revertStmt) do
+            throwStatement( blockBuilder, revertStmt, contractAst, functionAst )
+          end,
+          :Require => ->(requireStmt) do
+            requireStatement( blockBuilder, requireStmt, contractAst, functionAst )
+          end,
+        }
+
+        @logger.debug "#{__method__}: functionCallStmt&.functionCalled=#{functionCallStmt&.functionCalled}" if @logger.debug?
+        if functionCallStmt.isCallToReservedFunctionType
+          # dispatch Solidity well known function e.g. selfDestruct
+          # based on sexp_type of the resolved reference
+          Ethereum.dispatcher( dispatchSolidityFunctions, functionCallStmt.functionCalled.reference.sexp_type, functionCallStmt )
+        else
+          # "Normal" function calls
+          functionCallStatement( blockBuilder, functionCallStmt, contractAst, functionAst )
+        end
+        
+      end
+
+      # Translate =selfdestruct= statement into body 'blockBuilder' of
+      # Solidity contract 'contractAst' function 'functionAst.'
+      #
+      # Delegate implemention to {#Ethereum::ethDeleteAccount}
+      def selfdestructStmt(blockBuilder, selfdestructCallStmtAst, contractAst, functionAst )
+        @logger.debug( "#{__method__}: selfdestructCallStmtAst=#{selfdestructCallStmtAst}") if @logger.debug?
+
+        astRecipient = selfdestructCallStmtAst.arguments[0]
+        @logger.debug( "#{__method__}: astRecipient=#{astRecipient}") if @logger.debug?
+        
+        # Delete account by removing entries for currently running
+        # contract
+        ethApi.ethDeleteAccount( blockBuilder, astRecipient )
+        
+      end
+
+      # Translate :Assign statement assigning expression 'rval' to
+      # 'lval', where lval.sexp_type is :Identifier (assignment to
+      # elementary type variable), or lval.sexp_type is :IndexAccess
+      # (assignment to a mapping variable)
+      #
+      # Currently supports assigning to contract member variable
+      #    :ContractDefinition, and :FunctionDefinition (for return
+      #    value)
+      #
+      # @param assignStmtAst [Assignment] assing to 'lval' value in
+      #         'rval' using operator 'operator'
+      def assignStatement( blockBuilder, assignStmtAst )
+        @logger.debug( "#{__method__}: assignStmtAst=#{assignStmtAst}") if @logger.debug?
+        @logger.info( "#{__method__}: assignStmtAst.lval=#{assignStmtAst&.lval.sexp_type}")
+
+
+        # Should have pre-processed operator such as +=,  -=,  ...
+        raise TranslatorException, "Operator implemenation missing #{assignStmtAst}" unless assignStmtAst["operator"] == "="
+
+        dispatcherVariableLval = {
+          # Assign to contract state variable
+          :ContractDefinition => ->(assignStmtAst) do
+            variableAst = assignStmtAst.lval            
+            contractAst = variableAst.sexp_type == :IndexAccess ?
+                            variableAst.identifier.reference.scopeDefining :
+                            variableAst.sexp_type == :Identifier ? 
+                              variableAst.reference.scopeDefining :
+                              (raise TranslatorException, "Unsupported lval type #{assignStmtAst.lval}")
+            
+            expressionAst = assignStmtAst.rval
+            blockBuilder.assignTo do
+              variable ethApi.refStorageRoot
+              rval ethApi.ethAssignStatement( contractAst, variableAst, expressionAst )
+            end # assignTo
+          end, # lambda for :ContractDefinition
+          
+          # assign to function return value
+          :ResponseParameterList => ->(assignStatement) do
+            blockBuilder.returnValue(
+              assignStmtAst.lval["value"],
+              ethApi.dispatchExpression( assignStmtAst.rval ))
+          end , # lambda for :FunctionDefinition
+          
+        }
+
+        # Path to lval different for :Identifer and :IndexAccess
+        lvalScope = if ( assignStmtAst.lval.sexp_type == :Identifier )
+                      assignStmtAst&.lval&.reference&.scopeDefining&.sexp_type
+                    elsif ( assignStmtAst.lval.sexp_type == :IndexAccess )
+                      assignStmtAst.lval.identifier.reference&.scopeDefining&.sexp_type
+                    else
+                      raise TranslatorException, "Unsupported assigment to #{assignStmtAst&.lval} in #{assignStmtAst}" unless [:Identifier, :IndexAccess].include?( assignStmtAst&.lval.sexp_type )
+                    end
+        @logger.debug( "#{__method__}: lvalScope=#{lvalScope} for #{assignStmtAst.lval.sexp_type}") if @logger.debug?
+
+        # Call lambda(assignStmtAst.lval)  dispatcherVariableLval[lvalScope]
+        Ethereum.dispatcher( dispatcherVariableLval, lvalScope, assignStmtAst )
+      end
+
+      # Translate 'returnStmtAst' from function 'functionAst' in
+      # contract 'contractAst' to AL constructs 'blockBuilder.ret'
+      # and goto end (of function procedure).
+      #
+      # Edge cases for return expressions:
+      #
+      # * no return parameters for a function: -> ret(true)
+      #
+      # * tuple-parameter/array of parameters: -> ret(true,exprRecord),
+      #   where 'exprRecord' maps function return parameter to
+      #   'retExpr', where 'retExpr' are translated using
+      #   {#dispatchExpression} with array flatten (to deal with
+      #   return :TupleExpression vs. return array of expressions)
+      #
+      #
+      # @param blockBuilder [AL:BlockBuilder] AL block where statement
+      #        should be added, see {#dispatchBlockStatement}
+      #
+      # @param returnStmtAst see {#dispatchBlockStatement}
+      #
+      #
+      def returnStatement( blockBuilder, returnStmtAst, contractAst, functionAst )
+        
+        expressionAsts = returnStmtAst.children
+        @logger.debug "#{__method__}: expressionAsts=#{expressionAsts}" if @logger.debug?
+        @logger.info "#{__method__}: function '#{functionAst['name']}' returns #{expressionAsts.length} expressions: #{expressionAsts}" 
+
+        if expressionAsts.length == 0 
+          # just return status (response remains unchanged)
+          blockBuilder.ret true
+        else
+
+          # translate return expression (flatten for :TupleExpression)
+          retExpressions = expressionAsts.map do  |expressionAst|
+            ethApi.dispatchExpression( expressionAst )
+          end.flatten
+
+          # Assert param count == return expressions count
+          raise TranslatorException,
+                "Number of ret expressions #{retExpressions.length} " +
+                "!= number of return params #{functionAst.responseParameters.parameters.length}" if retExpressions.length != functionAst.responseParameters.parameters.length
+
+          # return TRUE, [ ret0 |-> expr0, ret1 |-> expr1, ... ]
+          blockBuilder.ret(
+            true,
+            ethApi.tlaRecord(
+              functionAst.responseParameters.parameters.map.with_index do |parameter, i|
+                ethApi.tlaRecordFieldDef( parameter["name"],  retExpressions[i] )
+              end
+            ))
+        end
+
+        # end execution (=jump to end label)
+        ethApi.ethActionGotoEnd( blockBuilder, contractAst["name"], functionAst["name"] )
+      end
+
+
+      # Translate 'requireSmtAst' to 'blockBuilder.failure' if
+      # expression ('requireSmtAst.expression') evaluates FALSE.
+      #
+      # @param functionCallAst [FunctionCall] Function call statement
+      #        for requiremet with exactly 1 argument for requirement
+      #        expression.
+      #      
+      #
+      def requireStatement( blockBuilder, functionCallAst, contractAst, functionAst )
+        
+        @logger.info "#{__method__} add throw #{functionCallAst}"
+        
+        raise "Require supports only one argument now #{functionCallAst.arguments.length} in #{functionCallAst.arguments}" unless functionCallAst.arguments.length == 1
+        
+        ifStmt = blockBuilder.ifThen( ethApi.not(ethApi.tlaParenthesis(ethApi.dispatchExpression( functionCallAst.arguments[0] )))) do
+          ifBlockBuilder = self
+          ifBlockBuilder.failure( ethApi.nEthnInterfaceOperation( contractAst["name"], functionAst["name"] ))
+        end
+      end
+
+      # Translate 'functionCallStmt' -statement into the body
+      # 'blockBuilder' of Solidity contract 'contractAst' function
+      # 'functionAst'.
+      #
+      #
+      def functionCallStatement( blockBuilder, functionCallStmt, contractAst, functionAst )
+        
+        @logger.debug "#{__method__}: functionCallStmt=#{functionCallStmt}" if @logger.debug?
+
+        # call target
+        functionCalled = functionCallStmt.callTarget # functionCallStmt.functionCalled.reference
+        contractCalled = functionCalled.enclosingScope
+        @logger.debug "#{__method__}: functionCalled=#{functionCalled}, contractCalled=#{contractCalled}" if @logger.debug?        
+
+        # :create, :call, :remote, :callcode, :delegatecall
+        callType = callType( functionCallStmt, contractAst, functionAst, contractCalled, functionCalled )
+        valueModifier = functionCallStmt.valueModified
+
+        
+        @logger.info "#{__method__}: callType=#{callType}, valueModifier=#{valueModifier},  caller=#{contractAst['name']}(#{functionAst["name"]}) called=#{contractCalled['name']}(#{functionCalled["name"]})"
+
+        # Use 'valueModifier' from f-call if present, defauls 0
+        valueModifierExpression = 
+          if valueModifier then
+            raise "Expect one argument in #{valueModifier.arguments} as value modifer in #{valueModifier} " if valueModifier.arguments.length != 1
+            ethApi.dispatchExpression(valueModifier.arguments.first)
+          else
+            ethApi.expression(0)
+          end
+        @logger.debug "#{__method__}: valueModifierExpression=#{valueModifierExpression.strOutput}" if @logger.debug?
+
+        # Evaluate arguments in function call (including common
+        # paremters recient, sender, originator, value)
+        parameters = ethApi.ethCallParameters(
+          callType, contractAst["name"], functionAst["name"],
+          
+          # Common parameters
+          ethApi.ethCallCommonRequestParameters( callType, contractAst["name"], functionAst["name"], functionCallStmt, valueModifierExpression ),
+
+          # Evaluate function call arguments
+          functionCallStmt.arguments.map.with_index do  |argument, parameter_index|
+            parameterAst = functionCalled.requestParameters.parameters[parameter_index]
+            # [paremeter name, AlExpression] -pair
+            [ parameterAst["name"],  ethApi.dispatchExpression(argument) ]
+          end
+        )  # parameters to function call
+
+        # dispatch actual call
+        case callType
+        when :create
+          ethApi.ethActionCall_create( blockBuilder, contractAst, functionAst, functionCallStmt, parameters, contractCalled, functionCalled  )
+        when :call
+          ethApi.ethActionCall_call( blockBuilder, contractAst, functionAst, functionCallStmt, parameters, contractCalled, functionCalled  )
+        when :callcode
+          ethApi.ethActionCall_callcode( blockBuilder, contractAst, functionAst, functionCallStmt, parameters, contractCalled, functionCalled  )
+        when :delegatecall
+          ethApi.ethActionCall_delegatecall( blockBuilder, contractAst, functionAst, functionCallStmt, parameters, contractCalled, functionCalled  )
+        else
+          raise TranslatorException, "Unknown callType #{callType}"
+        end
+      end
+
+
+      # @return [:create, :call, :remote, :callcode, :delegatecall]
+      #          callType for 'contractCaller(functionCaller)' calling
+      #          'contractCalled(functionCalled)'
+      #
+      # Symbol values returned corresponds to EVM mnemonics in
+      # Ethereum yellow paper appedix F, section 'System operations'.
+      def callType( functionCallStmt, contractCaller, functionCaller, contractCalled, functionCalled )
+        callType = 
+          if contractCalled['name'] ==  functionCalled['name']
+            :create
+          elsif functionCallStmt.functionCalled.sexp_type == :Identifier  # local call 
+            :delegatecall
+          # elsif # library ??
+          #   :callcode
+          else # functionCallStmt.functionCalled.sexp_type == :MemberAccess  # remote if called trough membar access
+            :call
+          end
+        @logger.info "#{__method__}: #{contractCaller["name"]}(#{functionCaller["name"]}) call to #{contractCalled["name"]}(#{functionCalled["name"]}) --> #{callType}"
+        callType
+      end
+      # 
+      # Triggering exception for 'throwSmtAst' is simply setting
+      # 'failure' on 'blockBuilder'
+      #
+      # @param blockBuilder [AL:BlockBuilder] AL block where statement
+      #        should be added, see {#dispatchBlockStatement}
+      
+      def throwStatement( blockBuilder, throwSmtAst, contractAst, functionAst )
+        @logger.info "#{__method__} add throw #{throwSmtAst}"
+        blockBuilder.failure( ethApi.nEthnInterfaceOperation( contractAst["name"], functionAst["name"] ))
+      end
+
+      # Translate Solidity 'ifStmtAst' to AL 'ifThen' and 'elseThen'
+      # blocks
+      def ifStatement( blockBuilder, ifStmtAst, contractAst, functionAst )
+        @logger.info "#{__method__} add if stmt for condition #{ifStmtAst.condition}"
+        # puts "ifStmtAst.conditiion=#{ifStmtAst.condition}"
+        ifStmt = blockBuilder.ifThen( ethApi.dispatchExpression(ifStmtAst.condition )) {
+          ifBlockBuilder = self
+          # add statements in ifBlock
+          ifStmtAst.ifThen.children do |stmt|
+            dispatchBlockStatement( ifBlockBuilder, stmt, contractAst, functionAst )
+          end
+          
+        }
+
+        if ( ifStmtAst.elseThen )
+          # else brach given - add corresponding elseBlock
+          ifStmt.elseThen {
+            
+            elseBlockBuilder = self
+            # add statements in elseBlock
+            ifStmtAst.elseThen.children do |stmt|
+              dispatchBlockStatement( elseBlockBuilder, stmt, contractAst, functionAst )
+            end
+            
+          }
+        end
+      end
+
+      # @!endgroup
+
+
+      # ------------------------------------------------------------------
+      # @!group Private helpers
+
+      # # @param mapper [Hash] key=symbol to choose, value = lamba
+      # # @param ast [AstSext] AST node to dispatch 
+      # def dispatcher( mapper, key, ast )
+        
+      #   @logger.debug( "#{__method__}: mapper=#{mapper.keys.join(',')} key=#{key} ast=#{ast}")
+
+      #   # Error checks
+      #   raise TranslatorException, "Missing dispatcher key to dispatch one #{mapper.keys.join(',')}. Error dispatching ast node: #{ast}"  if key.nil?
+      #   raise TranslatorException, "Dispatch key #{key} not found in known keys:#{mapper.keys.join(',')}. Error dispatching ast node: #{ast}" if mapper[key].nil?
+
+      #   # invoke lamba
+      #   mapper[key][ast]
+
+      # end
+
+      # @!endgroup
+
+
+
+      
+    end    # class
+  end
+end