henriquecbuss/elm-eos

This package provides a way to interact with the EOS blockchain, while maintaining Elm's type safety. In order to do so, it reads the ABI of the contracts you want to interact with, and generates all of the necessary Elm code to interact with them.

Overview

This package mainly serves to translate EOSIO types to Elm types. There is a CLI app that is responsible for generating code specific to the contracts you need. The exception to that is the Eos.Query module, which is used to send queries to the blockchain.

For example, let's say you have a contract named company.acc, with an accounts table, described by this struct:

{
    "name": "account",
    "base": "",
    "fields": [
        {
            "name": "account_name",
            "type": "name"
        },
        {
            "name": "balance",
            "type": "asset"
        }
    ]
}

In order to get data from that table, you would write some Elm code like this (all of the code that starts with Company.Acc is generated by the CLI app):

import Company.Acc.Table.Query
import Company.Acc.Table
import Eos.Query
import Http

fetchAccounts : (Result Http.Error (Eos.Query.Response Company.Acc.Table.Account) -> msg) -> Cmd msg
fetchAccounts toMsg =
    Company.Acc.Table.Query.account { scope = "company.acc" }
        |> Eos.Query.withLimit 100
        |> Eos.Query.send toMsg

You never need to define JSON encoders, decoders, or types for the data you're querying for. The generated code does all of that for you, including setting the target url (though you can override that if you need).

Here's a sneak peak of what the generated code looks like:

-- In file Company/Acc/Table/Query.elm

import Eos.Query

account : { scope : String } -> Eos.Query.Query Company.Acc.Table.Account

-- In file Company/Acc/Table.elm

import Eos.Name
import Eos.Asset

type alias Account =
    { accountName : Eos.Name.Name
    , balance : Eos.Asset.Asset
    }

Similarly, if you want to send data to the blockchain, all of the code is generated for you. For example, let's say you want to send a transfer action, described by this struct:

{
    "name": "transfer",
    "base": "",
    "fields": [
        {
            "name": "from",
            "type": "name"
        },
        {
            "name": "to",
            "type": "name"
        },
        {
            "name": "amount",
            "type": "asset"
        }
    ]
}

In order to generate JSON to send over to the blockchain, all you have to do is this:

import Json.Encode
import Eos.Name
import Eos.Permission
import Eos.Asset
import Company.Acc.Action

sendMoney : { currentUser : Eos.Name.Name, currentPermission : Eos.Permission.Permission to : Eos.Name.Name, amount : Eos.Asset.Asset } -> Json.Encode.Value
sendMoney { currentUser, currentPermission, to, amount } =
    Company.Acc.Action.Transfer
        { from = currentUser
        , to = to
        , amount = amount
        }
        |> Company.Acc.Action.encode [ { actor = currentUser, permission = currentPermission } ]

You can then send that JSON to the blockchain using the eosjs library (through a port), or using your preferred method. Check out the examples folder for complete examples.

Setup

There are a few moving pieces that need to work together in order to use henriquecbuss/elm-eos. Here's how to set them up:

1. Add the elm package as a dependency in your elm.json, along with elm/json, elm/http and NoRedInk/elm-json-decode-pipeline:

   elm install henriquecbuss/elm-eos
   elm install elm/json
   elm install elm/http
   elm install NoRedInk/elm-json-decode-pipeline

2. Install the elm-eos command line through npm. This is what you will use to generate Elm code for the EOSIO API. You can save it as a dev dependency to ensure everyone on your team has access to the same version:

   # With npm
   npm install --save-dev elm-eos
   
   
   # With yarn
   yarn add --dev elm-eos

3. Run the CLI tool to generate the Elm code for your contracts. If you installed like shown above, you can run with npx elm-eos, or create a script in your package.json like this:

   {
       "scripts": {
           "generate:eos": "elm-eos https://mydomain.com/v1/chain --contract my.first --contract my.second --output generated --base Contracts"
       }
   }

   This will generate files in Contracts/My/First and Contracts/My/Second

4. Now whenever you need to refresh the generated code, you can run npm run generate-eos.

CLI

The CLI tool is used to generate the Elm code for your contracts. It takes some arguments:

• URL: the base url of the contracts. For example: https://mydomain.com/v1/chain
• Output: the directory to write the generated code to. For example: generated
• Base: the base module name to use for the generated code. For example: My.Contract
• Contracts: the names of the contracts to generate code for. For example: --contract first --contract second

Joining all of that together, you can run the CLI like this:

elm-eos https://mydomain.com/v1/chain --contract first --contract second --output generated --base My.Contract

Only URL and Contracts are required.

Support

If you need any kind of support, feel free to open an issue on GitHub, or ping me @HenriqueBuss on the Elm Slack.