Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/EOSEssentials/Scala-API-Wrapper

A Scala wrapper for EOS RPC API
https://github.com/EOSEssentials/Scala-API-Wrapper

eos eosio scala

Last synced: 3 months ago
JSON representation

A Scala wrapper for EOS RPC API

Awesome Lists containing this project

README 

        
# EOS RPC API for Scala



**WARNING** This version is currently built for Dawn2 and highly out of sync with the EOSIO software.



A basic Scala wrapper for the [EOS](https://github.com/EOSIO) blockchain api. Under the [MIT License](https://raw.githubusercontent.com/nsjames/EOS-Scala-RPC-API/master/license)



---



### Requirements

* Scala version: 2.12.4

* SBT version: 0.13.16



## Installation



**Getting the repo**



Add the sbt dependency to your `build.sbt` file.

```

"org.nsjames" %% "eos-scala-rpc-api" % "1.0-SNAPSHOT"

```

*Not on maven yet, but you may publish locally for now, you can clone and use `sbt publishLocal`*



---



**Configuration**



Create a new folder in your project's base directory called `conf`. Inside of that folder create a

configuration file called `application.conf` which should have the following properties.

```

httpClient {

  connectTimeout=5000

  readTimeout=5000

}



eos {

  // Set to some endpoint running eosd.  

  nodes = ["http://127.0.0.1:8888"]

}

```

*For more info on the `application.conf` file you can refer to the 

[lighbend config github](https://github.com/lightbend/config)*



In your `build.sbt` file add the following line to bring the `/conf/` directory into

your project.

```

resourceDirectory in Compile := baseDirectory.value / "conf"

```



## A few notes: 



* For ease of use, this library comes as a Singleton Object. 

You **do not** need to instantiate it or inject it as a dependency into your classes or tests.



* All methods will throw an easily catchable `EOSApiException`. 



* All methods can be accessed via the `EOSApis` object. Some methods (`sendMessage` and `sendMessages`)

are **only** accessible through the `EOSApis` object.



* All methods are asynchronous futures.



## Example usages



You can set a local variable for the `EOSApis` object for easier use, or you can use it as is.

```

val eos = EOSApis

eos.wallet.create()

--

or just

-- 

EOSApis.wallet.create()

```



**Create a new wallet**

```

EOSApis.wallet.create("my-new-wallet") map { password =>

    // If the creation is successful, you will be returned a password.

    // If not it will throw an exception with the error from the blockchain as a message.

    ...

}

```



**Open and unlock a wallet** ( example of catching throws )

```

try {

    for {

        opened <- EOSApis.wallet.open(walletName)

        unlocked <- EOSApis.wallet.unlock(walletName, walletPassword)

    } yield {

        // Wallet is now open, unlocked and ready for use

    }

} catch {

    case (e:EOSApiException) => 

        e.printStackTrace(); // Dont forget this. It's not nice to swallow.

        // Wallet opening or unlocking failed, check the trace for errors

}

```



**Sending transactions**



For custom contracts you will have to create a model to support it. The one below comes with

eosd and for example purposes also comes with this library.



For each action, you will need to create a case class to support it.



**Important: Always make sure your case classes have a companion object with an implicit

format for JSON parsing**

```

object CurrencyContract {

    // Each action in the contract will need a case class and a companion object

    case class Transfer(from:String, to:String, quantity:Long)

    object Transfer { implicit val format = Json.format[Transfer] }

}

```



Just for ease of use, i've added a few helper methods to the Transfer case class to convert it 

from an Action to a Method. **You do not have to do this**, but it's always a good idea to keep logic like this

on the model, and not in your controllers or services.

```

case class Transfer(from:String, to:String, quantity:Long){

    def message:Message = Message("currency", "transfer", List(MessageAuthorization(from, "active")))

    def scopes:List[String] = List(from, to)

}

```

Let's break those down for a second.

* The `Transfer` is the `data` that is sent to the contract.

* The `Message` is the `action` that is sent to the contract.

* `Scopes` are the accounts involved in this transfer action.



---



Now, we can instantiate a `Transfer` action and use it to send a message to the blockchain.



The `sendMessage` method does a few things. It converts your message into an unsigned transaction,

grabs the latest irreversible block off the chain, binds it to the transaction, uses the public key

supplied to sign the transaction, converts it to binary, and then sends it to the blockchain.

You can open up the `EOSApis` object to see how it's done.

```

try {

    val transfer = CurrencyContract.Transfer("currency", "inita", 10)

    val messageBuilder = MessageBuilder(transfer.message, Json.toJson(transfer), transfer.scopes, activePublicKeyUsedToCreateContract)

    eos.sendMessage(messageBuilder) map { transaction =>

        ...

    }

} catch { case (e:EOSApiException) =>  // Transaction failed. }

```



---



**Using the standalone apis**



You can also use each API on it's own.

```

ChainAPI.getBlock(blockNumOrID)

//or

EOSApis.chain.getBlock(blockNumOrID)

-----------------------------------------------

WalletAPI.lock(walletName)

//or

EOSApis.wallet.lock(walletName)

-----------------------------------------------

AccountHistoryAPI.getTransactions(accountName)

//or

EOSApis.accountHistory.getTransactions(accountName)



```