Icon

Build statusHex pmhex.pm downloadsCoverage Status

"Knowledge is of no value unless you put it into practice." - Anton Chekhov

Icon is a library for interacting with the interoperable decentralized aggregator network ICON 2.0.

This document gives a general overview of the current state of the project and its future:

Motivation

The motivation for building a SDK in Elixir is to be able to use:

while writing client applications for ICON 2.0.

This library is a work in progress, so if you want to use a production ready SDK you're better off using one of the official ones:

Overview

Every single JSON API v3 method is already implemented (no BTP nor IISS extensions yet).

For most applications, we'll need just two modules:

Though this SDK was heavily inspired by the ICON Python SDK, it difers slightly from it:

Example: Transferring ICX

The following example shows how to send 1 ICX from our wallet to another:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...")
iex> Icon.transfer(identity, "hx2e243ad926ac48d15156756fce28314357d49d83", 1_000_000_000_000_000_000)
{:ok, "0xd579ce6162019928d874da9bd1dbf7cced2359a5614e8aa0bf7cf75f3770504b"}

Note: In this library, ICX is always expressed in loop as units, where 1 ICX = 10¹⁸ loop.

Example: SCORE Transaction Call

The following example calls a fuction in a SCORE in the Sejong testnet:

iex> identity = Icon.RPC.Identity.new(private_key: "8ad9...", network_id: :sejong)
iex> params = %{
...>   _strategy: "cx31f04b8d24628463db5ac9f04a7d33ba32e44680",
...>   _start: 1,
...>   _end: 51
...> }
iex> schema = %{
...>   _strategy: {:score_address, required: true},
...>   _start: :integer,
...>   _end: :integer
...> }
iex> Icon.transaction_call(
...>   identity,
...>   "cx9cd4af2976c8ffabf3146d1d166e83a6dd689d50",
...>   "claim",
...>   params,
...>   call_schema: schema
...> )
{:ok, "0xd579ce6162019928d874da9bd1dbf7cced2359a5614e8aa0bf7cf75f3770504b"}

Note: The previous example was taken from Optimus Finance SCORE for claiming rewards from strategies.

Wallets and Node Connections

Every request to the API requires an Icon.RPC.Identity.t() instance. There are two types of identities:

Note: the private key is always redacted when inspecting the Icon.RPC.Identity.t() struct. The idea is to be able to safely log an identity without compromising the security of the underlying wallet by revealing sensitive data.

For more customization options, checkout the module Icon.RPC.Identity documentation.

Realtime Updates

It is possible to subscribe to the ICON 2.0 websocket to get either or both block and event log updates in realtime. It leverages Yggdrasil (built with Phoenix.PubSub) for handling incoming messages.

The channel has two main fields:

Important: We need to be careful when using from_height in the channel because Yggdrasil will restart the synchronization process from the chosen height if the process crashes.

Example: Subscribing to Blocks

We can subscribe to blocks using Yggdrasil.subscribe/1:

iex> channel = [name: %{source: :block}, adapter: :icon]
iex> Yggdrasil.subscribe(channel)
:ok

and our subscriber process will get notifications in its mailbox every time a block is produced. If we use flush/0 to flush the messages from the IEX mailbox, we'll get something like the following:

iex> flush()
{:Y_CONNECTED, %Yggdrasil.Channel{adapter: :icon, ...}}
{:Y_EVENT, %Yggdrasil.Channel{adapter: :icon, ...}, %Icon.Schema.Types.Block.Tick{height: 42, hash: "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"}}
...

When we're done, we can unsubscribe using the following:

iex> Yggdrasil.unsubscribe(channel)
:ok

Note: Also we can subscribe to one or more events using the block subscription. We'll get both Icon.Schema.Types.Block.Tick.t() and Icon.Schema.Types.EventLog.t(). For this, we need to provide a list of events we want to subscribe to in the data field: 

iex> channel = [
...>   adapter: :icon,
...>   name: %{
...>     source: :block,
...>     data: [
...>       %{
...>         event: "Transfer(Address,Address,int)"
...>       }
...>     ]
...>   }
...> ]
iex> Yggdrasil.subscribe(channel)
:ok

For more info about the notifications, check the next section.

Example: Subscribing to Events

Following the previous example, if we're only interested in a single event, we can just subscribe to it e.g. the following shows a subscription to the event Transfer(Address,Address,int) for the SCORE address cx31f04b8d24628463db5ac9f04a7d33ba32e44680:

iex> channel = [
...>   adapter: :icon,
...>   name: %{
...>     source: :event,
...>     data: %{
...>       addr: "cx31f04b8d24628463db5ac9f04a7d33ba32e44680",
...>       event: "Transfer(Address,Address,int)"
...>     }
...>   }
...> ]
iex> Yggdrasil.subscribe(channel)
:ok

Our subscriber process will get notifications in its mailbox every time an event matches our query. If we use flush/0 to flush the messages from the IEX mailbox, we'll get something like the following:

iex> flush()
{:Y_CONNECTED, %Yggdrasil.Channel{adapter: :icon, ...}}
{:Y_EVENT, %Yggdrasil.Channel{adapter: :icon, ...}, %Icon.Schema.Types.Block.Tick{height: 42, hash: "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"}}
{:Y_EVENT, %Yggdrasil.Channel{adapter: :icon, ...}, %Icon.Schema.Types.EventLog{header: "Transfer(Address,Address,int)", indexed: ["hxfd7e4560ba363f5aabd32caac7317feeee70ea57", "hxbe7e4560ba363f5aabd32caac7317feeee70ea57"], ...}}
...

Also, when we're done, we can unsubscribe using the following:

iex> Yggdrasil.unsubscribe(channel)
:ok

TODO

The following is a list of functionalities this SDK aims to support in the future:

Installation

The package is available in Hex and can be installed by adding icon to your list of dependencies in mix.exs:

def deps do
  [
    {:icon, "~> 0.2"}
  ]
end

Containerized Testing

If you just want to try it out, you can run this project inside a docker container with Elixir:

$ git clone https://github.com/alexdesousa/icon.git
$ cd icon/
$ docker run -it --rm -v $PWD:/data -w /data elixir:latest iex -S mix

Note: For certain docker setups, you'll need to add sudo at the beginning of the command.

While in the IEx shell, you can check the documentation for any module and function just by typing h in front of it e.g:

iex> h Icon.transfer
# ... shows documentation for `Icon.transfer/3` and `Icon.transfer/4` ...

Installing Elixir

If you want to install Elixir, I recommend using asdf to get it (you'll need both Erlang and Elixir to be able to run this library).

In Ubuntu/Linux Mint, you'll need the following dependencies to be able to build Erlang:

$ sudo apt install \
    build-essential \
    autoconf \
    m4 \
    libncurses5-dev \
    libwxgtk3.0-gtk3-dev \
    libgl1-mesa-dev \
    libglu1-mesa-dev \
    libpng-dev \
    libssh-dev \
    unixodbc-dev \
    xsltproc \
    fop

Once they're installed you can add Erlang and build it:

$ asdf plugin-add erlang
$ asdf install erlang 24.2 # This step takes some time.
$ asdf global erlang 24.2

Finally, you can install Elixir running the following:

$ asdf plugin-add elixir
$ asdf install elixir 1.13.2-otp-24
$ asdf global elixir 1.13.2-otp-24

Author

Alex de Sousa (a.k.a. Etadelius).

License

Icon is released under the MIT License. See the LICENSE file for further details.