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.

Table of contents

• 🏃 Getting started
  • ️🏗️ Scaffold new app
  • ➕ Add to existing app
• 📕 Overview
  • 📖 Examples
• 🤖 CLI
• 🆘 Support

Getting started

Scaffold new app

If you want to start a new app, you can use the create-elm-eos-dapp tool to scaffold a new app for you. It will generate anew app with all of the necessary dependencies and code to get you started, along with linters, formatters, and all of that good stuff.

• With yarn:

yarn create elm-eos-dapp

• With npm:

npx create-elm-eos-dapp

• With pnpm:

pnpm create elm-eos-dapp

The scripts in the generated package.json use npm, so you have to manually change them if you want to use yarn or pnpm.

Add to existing app

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, and install these libraries:

   elm install henriquecbuss/elm-eos
   elm install elm/json
   elm install elm/http
   elm install elm/time
   elm install NoRedInk/elm-json-decode-pipeline
   elm install elm-community/maybe-extra
   elm install elm-community/result-extra

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

   • With pnpm:

   pnpm add -D 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.

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. The contractExplorer example shows how to integrate with external wallets to submit transactions.

Examples

You can take a look at the examples folder for complete examples (each one has more detailed information in their README.md):

• memberFetching (source | live demo): a simple example of fetching data from the blockchain and displaying it in a table. This is the simplest example there is, and it's a good place to start.
• transfer (source | live demo): a more complex example, where you can send a transfer to the blockchain. This is an example for when you know what actions do and which ones you want to use.
• contractExplorer (source | live demo): an even more complex example, where you can explore the tables and actions of multiple contracts. This is an example for when you want to explore the API of a contract, and see what actions and tables it has. This example also includes integration with third-party wallets using eos-transit. This app is roughly what the tool generation does for you if you ask it to generate an app based on some contracts.

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.