Add doctests

Author: samuelmanzanera

lib/bls_ex.ex

@@ -1,64 +1,72 @@
 defmodule BlsEx do
+  @moduledoc """
+  BlsEx provides utility to leverage BLS signatures through WASM
+  """
   alias __MODULE__.Keystore
 
   @doc """
-  Creates a new BLS keystore
+  Verifies a single BLS signature
 
   ## Examples
 
-      iex> {:ok, pid} = BlsEx.new_keystore("myseed")
+      iex> {:ok, pid} = BlsEx.Keystore.start_link(seed: "myseed")
       iex> {:ok, public_key} = BlsEx.Keystore.get_public_key(pid)
       iex> {:ok, signature} = BlsEx.Keystore.sign(pid, "hello")
-  """
-  @spec new_keystore(binary()) :: GenServer.on_start()
-  def new_keystore(seed) do
-    Keystore.start_link(seed: seed)
-  end
-
-  @doc """
-  Verifies a single BLS signature
+      iex> BlsEx.verify_signature(public_key, "hello", signature)
+      {:ok, true}
   """
   @spec verify_signature(public_key :: binary(), message :: binary(), signature :: binary()) ::
           {:ok, boolean()} | {:error, any()}
   defdelegate verify_signature(public_key, message, signature), to: __MODULE__.StandaloneWasm
 
   @doc """
   Aggregate BLS signatures
+
+  ## Examples
+
+      iex> {:ok, pid} = BlsEx.Keystore.start_link(seed: "myseed")
+      iex> {:ok, public_key1} = BlsEx.Keystore.get_public_key(pid)
+      iex> {:ok, signature1} = BlsEx.Keystore.sign(pid, "hello")
+      iex> {:ok, pid2} = BlsEx.Keystore.start_link(seed: "myseed2")
+      iex> {:ok, public_key2} = BlsEx.Keystore.get_public_key(pid2)
+      iex> {:ok, signature2} = BlsEx.Keystore.sign(pid2, "hello")
+      iex> BlsEx.aggregate_signatures([signature1, signature2], [public_key1, public_key2])
   """
   @spec aggregate_signatures(signatures :: list(binary()), public_keys :: list(binary())) ::
           {:ok, binary()} | {:error, any()}
   defdelegate aggregate_signatures(signatures, public_keys), to: __MODULE__.StandaloneWasm
 
   @doc """
   Aggregate BLS public keys
+
+  ## Examples
+
+      iex> {:ok, pid} = BlsEx.Keystore.start_link(seed: "myseed")
+      iex> {:ok, public_key1} = BlsEx.Keystore.get_public_key(pid)
+      iex> {:ok, pid2} = BlsEx.Keystore.start_link(seed: "myseed2")
+      iex> {:ok, public_key2} = BlsEx.Keystore.get_public_key(pid2)
+      iex> {:ok, _aggregated_public_key} = BlsEx.aggregated_public_keys([public_key1, public_key2])
   """
   @spec aggregated_public_keys(public_keys :: list(binary())) :: {:ok, binary()} | {:error, any()}
   defdelegate aggregated_public_keys(public_keys), to: __MODULE__.StandaloneWasm
 
   @doc """
   Verifies an aggregated BLS signature
+
+  ## Examples
+
+      iex> {:ok, pid} = BlsEx.Keystore.start_link(seed: "myseed")
+      iex> {:ok, public_key1} = BlsEx.Keystore.get_public_key(pid)
+      iex> {:ok, signature1} = BlsEx.Keystore.sign(pid, "hello")
+      iex> {:ok, pid2} = BlsEx.Keystore.start_link(seed: "myseed2")
+      iex> {:ok, public_key2} = BlsEx.Keystore.get_public_key(pid2)
+      iex> {:ok, signature2} = BlsEx.Keystore.sign(pid2, "hello")
+      iex> {:ok, aggregated_signature} = BlsEx.aggregate_signatures([signature1, signature2], [public_key1, public_key2])
+      iex> BlsEx.verify_aggregated_signature( [public_key1, public_key2], "hello", aggregated_signature)
+      {:ok, true}
   """
   @spec verify_aggregated_signature(list(binary()), binary(), binary()) ::
           {:ok, boolean()} | {:error, any()}
   defdelegate verify_aggregated_signature(public_keys, message, signature),
     to: __MODULE__.StandaloneWasm
-
-  def test() do
-    {:ok, keystore1} = new_keystore("test")
-    # {:ok, keystore2} = new_keystore("test2")
-    # {:ok, public_key1} = Keystore.get_public_key(keystore1)
-    # {:ok, public_key2} = Keystore.get_public_key(keystore2)
-    # {:ok, signature1} = Keystore.sign(keystore1, "hello")
-    # # # IO.inspect(Base.encode16(signature1))
-    # {:ok, signature2} = Keystore.sign(keystore2, "hello")
-    # # IO.inspect(Base.encode16(signature2))
-
-    # verify_signature(public_key1, "hello", signature1)
-    # #
-    # {:ok, agg_signature} =
-    #   aggregate_signatures([signature1, signature2], [public_key1, public_key2])
-
-    # # # IO.inspect(Base.encode16(agg_signature))
-    # verify_aggregated_signature([public_key1, public_key2], "hello", agg_signature)
-  end
 end

lib/bls_ex/keystore.ex

@@ -1,8 +1,28 @@
 defmodule BlsEx.Keystore do
+  @doc """
+  Represents a keystore holding a the wasm instance for the given private key
+
+  To use the keystore, you have to instanciate it with `start_link/1` and later use either `sign/2` or `get_public_key/1`
+
+  ## Examples
+
+      iex> {:ok, pid} = BlsEx.Keystore.start_link(seed: "myseed")
+      iex> {:ok, _signature} = BlsEx.Keystore.sign(pid, "hello")
+  """
+
   use GenServer
 
   @wasm_path Application.compile_env!(:bls_ex, :wasm_path)
 
+  @type options :: [seed: binary()]
+
+  @doc """
+  Start a new keystore instance.
+
+  It requires to pass a keyword list options:
+  - `seed`: The private key entropy used to generate public key and sign data
+  """
+  @spec start_link(options) :: GenServer.on_start()
   def start_link(arg \\ []) do
     GenServer.start_link(__MODULE__, arg)
   end
@@ -37,16 +57,21 @@ defmodule BlsEx.Keystore do
     }
 
     {:ok, plugin} = Extism.Plugin.new(manifest)
-    {:ok, %{plugin: plugin, seed_fn: fn -> seed end}}
+
+    {:ok,
+     %{
+       plugin: plugin,
+       seed: seed
+     }}
   end
 
   defp seed_digest(seed), do: :crypto.hash(:sha512, seed)
 
-  def handle_call(:get_public_key, _from, state = %{plugin: plugin, seed_fn: seed_fn}) do
+  def handle_call(:get_public_key, _from, state = %{plugin: plugin, seed: seed}) do
     case Extism.Plugin.call(
            plugin,
            "getPublicKey",
-           Base.encode16(seed_fn.())
+           Base.encode16(seed)
          ) do
       {:ok, public_key_hex} ->
         {:reply, {:ok, Base.decode16!(public_key_hex, case: :mixed)}, state}
@@ -56,11 +81,11 @@ defmodule BlsEx.Keystore do
     end
   end
 
-  def handle_call({:sign, message}, _from, state = %{plugin: plugin, seed_fn: seed_fn}) do
+  def handle_call({:sign, message}, _from, state = %{plugin: plugin, seed: seed}) do
     case Extism.Plugin.call(
            plugin,
            "signData",
-           Jason.encode!(%{seed: Base.encode16(seed_fn.()), data: message})
+           Jason.encode!(%{seed: Base.encode16(seed), data: message})
          ) do
       {:ok, signature_hex} ->
         {:reply, {:ok, Base.decode16!(signature_hex, case: :mixed)}, state}