Deleted Test - Not needed anymore

README.md

@@ -13,13 +13,12 @@ the [Elixium Network](https://www.elixiumnetwork.org)
 {:ok, ref} = WaspVM.start() # Start WaspVM
 WaspVM.load_file(ref, "path/to/wasm/file.wasm") # Load a module
 WaspVM.execute(ref, "some_exported_function") # Call a function
-# => {:ok, :function_return_value}
+# => {:ok, total_gas_cost, :function_return_value}
 ```
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `wasp_vm` to your list of dependencies in `mix.exs`:
+Add `wasp_vm` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do

lib/decoding/global_section_parser.ex

@@ -1,7 +1,6 @@
 defmodule WaspVM.Decoder.GlobalSectionParser do
   alias WaspVM.LEB128
   alias WaspVM.OpCodes
-  alias WaspVM.Module
   alias WaspVM.Decoder.Util
   require IEx
 

lib/decoding/name_section_parser.ex

@@ -1,6 +1,8 @@
 defmodule WaspVM.Decoder.NameSectionParser do
   alias WaspVM.LEB128
 
+  @moduledoc false
+
   def parse(binary) do
     binary
     |> parse_subsections()

lib/execution/frame.ex

@@ -1,4 +1,4 @@
 defmodule WaspVM.Frame do
-  defstruct [:module, :instructions, :locals, labels: [], snapshots: []]
+  defstruct [:module, :instructions, :locals, :gas_limit, labels: [], snapshots: []]
   @moduledoc false
 end

lib/wasp_vm.ex

@@ -51,10 +51,76 @@ defmodule WaspVM do
   @doc """
     Call an exported function by name from the VM. The function must have
     been loaded in through a module using load_file/2 or load/2 previously
+
+  ## Usage
+  ### Most basic usage for a simple module (no imports or host functions):
+
+  #### Wasm File (add.wat)
+  ```
+  (module
+   (func (export "basic_add") (param i32 i32) (result i32)
+    get_local 0
+    get_local 1
+    i32.add
+   )
+  )
+  ```
+  Use an external tool to compile add.wat to add.wasm (compile from text
+  representation to binary representation)
+
+      {:ok, pid} = WaspVM.start() # Start the VM
+      WaspVM.load_file(pid, "path/to/add.wasm") # Load the module that contains our add function
+
+      # Call the add function, passing in 3 and 10 as args
+      {:ok, gas, result} = WaspVM.execute(pid, "basic_add", [3, 10])
+
+  ### Executing modules with host functions:
+
+  #### Wasm file (log.wat)
+  ```
+  (module
+    (import "env" "consoleLog" (func $consoleLog (param f32)))
+    (export "getSqrt" (func $getSqrt))
+    (func $getSqrt (param f32) (result f32)
+      get_local 0
+      f32.sqrt
+      tee_local 0
+      call $consoleLog
+
+      get_local 0
+    )
+  )
+  ```
+  Use an external tool to compile log.wat to log.wasm (compile from text
+  representation to binary representation)
+
+      {:ok, pid} = WaspVM.start() # Start the VM
+
+      # Define the imports used in this module. Keys in the import map
+      # must be strings
+      imports = %{
+        "env" => %{
+          "consoleLog" => fn x -> IO.puts "its \#{x}" end
+        }
+      }
+
+      # Load the file, passing in the imports
+      WaspVM.load_file(pid, "path/to/log.wasm", imports)
+
+      # Call getSqrt with an argument of 25
+      WaspVM.execute(pid, "getSqrt", [25])
+
+  Program execution can also be limited by specifying a `:gas_limit` option:
+
+      WaspVM.execute(pid, "some_func", [], gas_limit: 100)
+
+  This will stop execution of the program if the accumulated gas exceeds 100
   """
-  @spec execute(pid, String.t(), list) :: :ok | {:ok, any} | {:error, any}
-  def execute(ref, func, args \\ []) do
-    GenServer.call(ref, {:execute, func, args}, :infinity)
+  @spec execute(pid, String.t(), list, list) :: :ok | {:ok, any} | {:error, any}
+  def execute(ref, func, args \\ [], opts \\ []) do
+    opts = Keyword.merge([gas_limit: :infinity], opts)
+
+    GenServer.call(ref, {:execute, func, args, opts}, :infinity)
   end
 
   @doc """
@@ -73,7 +139,7 @@ defmodule WaspVM do
     {:reply, {:ok, module}, Map.merge(vm, %{modules: modules, store: store})}
   end
 
-  def handle_call({:execute, fname, args}, _from, vm) do
+  def handle_call({:execute, fname, args, opts}, _from, vm) do
     {func_addr, _module} =
       vm.modules
       |> Map.values()
@@ -94,23 +160,23 @@ defmodule WaspVM do
     {reply, vm} =
       case func_addr do
         :not_found -> {{:error, :no_exported_function, fname}, vm}
-        addr -> execute_func(vm, addr, args)
+        addr -> execute_func(vm, addr, args, opts[:gas_limit])
       end
 
     {:reply, reply, vm}
   end
 
   def handle_call(:vm_state, _from, vm), do: {:reply, vm, vm}
 
-  @spec execute_func(WaspVM, integer, list) :: tuple
-  defp execute_func(vm, addr, args) do
+  @spec execute_func(WaspVM, integer, list, :infinity | integer) :: tuple
+  defp execute_func(vm, addr, args, gas_limit) do
     stack = Enum.reduce(args, [], & [&1 | &2])
 
-    {vm, stack} = Executor.create_frame_and_execute(vm, addr, stack)
+    {vm, gas, stack} = Executor.create_frame_and_execute(vm, addr, gas_limit, 0, stack)
 
     case vm do
       tuple when is_tuple(tuple) -> tuple
-      _ -> {{:ok, hd(stack)}, vm}
+      _ -> {{:ok, gas, hd(stack)}, vm}
     end
   end
 end

mix.exs

@@ -10,7 +10,17 @@ defmodule WaspVM.MixProject do
       deps: deps(),
       description: description(),
       package: package(),
-      source_url: "https://github.com/ElixiumNetwork/WaspVM"
+      source_url: "https://github.com/ElixiumNetwork/WaspVM",
+      docs: docs()
+    ]
+  end
+
+  defp deps do
+    [
+      {:binary, "~> 0.0.5"},
+      {:decimal, "~> 1.0"},
+      {:ex_doc, ">= 0.0.0", only: :dev},
+      {:benchee, "~> 0.13", only: :dev},
     ]
   end
 
@@ -36,11 +46,10 @@ defmodule WaspVM.MixProject do
     ]
   end
 
-  defp deps do
+  defp docs do
     [
-      {:binary, "~> 0.0.5"},
-      {:decimal, "~> 1.0"},
-      {:ex_doc, ">= 0.0.0", only: :dev},
+      source_url: "https://github.com/ElixiumNetwork/WaspVM",
+      extras: ["README.md"]
     ]
   end
 end

mix.lock

@@ -1,6 +1,8 @@
 %{
+  "benchee": {:hex, :benchee, "0.13.2", "30cd4ff5f593fdd218a9b26f3c24d580274f297d88ad43383afe525b1543b165", [:mix], [{:deep_merge, "~> 0.1", [hex: :deep_merge, repo: "hexpm", optional: false]}], "hexpm"},
   "binary": {:hex, :binary, "0.0.5", "20d816f7274ea34f1b673b4cff2fdb9ebec9391a7a68c349070d515c66b1b2cf", [:mix], [], "hexpm"},
   "decimal": {:hex, :decimal, "1.6.0", "bfd84d90ff966e1f5d4370bdd3943432d8f65f07d3bab48001aebd7030590dcc", [:mix], [], "hexpm"},
+  "deep_merge": {:hex, :deep_merge, "0.2.0", "c1050fa2edf4848b9f556fba1b75afc66608a4219659e3311d9c9427b5b680b3", [:mix], [], "hexpm"},
   "earmark": {:hex, :earmark, "1.3.1", "73812f447f7a42358d3ba79283cfa3075a7580a3a2ed457616d6517ac3738cb9", [:mix], [], "hexpm"},
   "ex_doc": {:hex, :ex_doc, "0.19.2", "6f4081ccd9ed081b6dc0bd5af97a41e87f5554de469e7d76025fba535180565f", [:mix], [{:earmark, "~> 1.2", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.10", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm"},
   "makeup": {:hex, :makeup, "0.6.0", "e0fd985525e8d42352782bd76253105fbab0a783ac298708ca9020636c9568af", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm"},