etherest v0.1.0

ETHEREST JavaScript Client

ETHEREST provides a simple way to make calls and transactions to the Ethereum blockchain using a REST-like API. This library is a lightweight and flexible interface to the API which can be used in both Node.js and browser based projects. It's a fast way to start getting data from and mutating the blockchain without running your own node.

Installation

Node.js

You can install ETHEREST as an npm module: npm install etherest

As well as using server side, it's safe to webpack or browserify the npm module for use in browsers.

Browsers

A standalone library for web browsers is also provided which can be embeded onto your page using jsdlvr's npm cdn:

<script src="https://cdn.jsdelivr.net/npm/etherest@0.1/dist/etherest.min.js"></script>

The browser script defines a global variable Etherest which is the same as the entry point of the default export of the npm module.

Example Usage

Call Without an ABI (Sandiwch Shop)

Etherest
.address('0x4dc924EeB4D87ab938f5a72fC0ef4460f6b35a8A')
.method('getSandwichInfoCaloriesPrice')
.param(2, 'uint')
.returns(['string', 'string', 'string', 'uint256'])
.call()
.then(function (result) {
	console.log("Got info from the sandwich shop!");
	console.log(result);
});

Transaction (Rouleth)

Etherest
.address('0x91A57B2F6FA86B373Bce5716eb26C81cbb004223')
.method('betOnNumber')
.param(7, 'uint')
.sendTransaction({
	from: '0xd3c14E7E6Feb41d8210412fc77ef94a72d8B089b',
	privateKey: '5172eb05eb9b27e15d4fe963157967b2d6e13e128e79d9b6dc27acf4dcf654ab',
	value: 0.01
})
.then(function (txid) {
	console.log("Transaction ID: " + txid);
});

Call Using a Public ABI (Basic Attention Token)

Etherest
.address('0x0D8775F648430679A709E98d2b0Cb6250d2887EF')
.loadAbi()
.then(function (basicAttentionToken) {
	basicAttentionToken
	.tokenExchangeRate()
	.then(function (rate) {
		console.log("1 ETH = " + rate + " Basic Attention Tokens");
	});
});

Got a private abi you want to use instead? Just provide it by calling Etherest.address(...).abi([...]). See the full documentation below for a deep dive into the library's full functionality.

Etherest API

To learn more about the ETHEREST API check out some of our getting started guides:

• Introducing ΞTHEREST — the easiest way to interact with the Ethereum Blockchain
• Automate your ÐICE dividend collection every quarter with ΞTHEREST
• Making a call to Ethereum’s pre-eminent eating establishment

Full Documentation

Etherest

Kind: global class

• Etherest
  • new Etherest([options])
  • .address(address, [network]) ⇒ Address
  • .request([options]) ⇒ Promise
  • .call([path]) ⇒ Promise
  • .sendTransaction([path], options) ⇒ Promise

new Etherest(options)

The main entry point to the client library, can be instantiated or used as a static class upon which all instance methods are available

Returns: Etherest - new Etherest instance

etherest.address(address, network) ⇒ Address

Creates a new address object linked to this etherest instance for executing queries against

Kind: instance method of Etherest
Returns: Address - new address instance

etherest.request(options) ⇒ Promise

Executes a request against this instance's etherest server

Kind: instance method of Etherest
Returns: Promise - promise which resolves when the request is complete with the response from etherest

etherest.call(path) ⇒ Promise

Executes a call request against the etherest server

Kind: instance method of Etherest
Returns: Promise - promise which resolves when the call is completed with the data returned from etherest

etherest.sendTransaction(path, options) ⇒ Promise

Sends a transaction to the etherest server

Kind: instance method of Etherest
Returns: Promise - a promise which resolves when the transaction has been submitted with an Ethereum txid

Address

Kind: global class

• Address
  • new Address(etherest, address, [network])
  • .query(method, params) ⇒ Query
  • .method(name, ...param) ⇒ Query
  • .defineMethod(name, params, returns) ⇒ function
  • .defineCall(name, params, returns) ⇒ function
  • .defineTransaction(name, params) ⇒ function
  • .abi(abi) ⇒ Address
  • .loadAbi() ⇒ Promise
  • .urlEncode(suffix) ⇒ string
  • .call(path) ⇒ Promise
  • .sendTransaction(path, options) ⇒ Promise

new Address(etherest, address, network)

Represents an address on the blockchain

Returns: Address - new Address instance

address.query(method, params) ⇒ Query

Creates a new query object which is linked to this address instance

Kind: instance method of Address
Returns: Query - new query instance

address.method(name, ...param) ⇒ Query

Creates a new query object for a method with params passed in as arguments

Kind: instance method of Address
Returns: Query - new query instance

address.defineMethod(name, params, returns) ⇒ function

Add a method to this instance with a given name and list of param types which returns a query when invoked

Kind: instance method of Address
Returns: function - reference to the function defined

address.defineCall(name, params, returns) ⇒ function

Add a method to this instance with a given name and list of param types which performs a call when invoked

Kind: instance method of Address
Returns: function - reference to the function defined

address.defineTransaction(name, params) ⇒ function

Add a method to this instance with a given name and list of param types which creates a transaction when invoked

Kind: instance method of Address
Returns: function - reference to the function defined

address.abi(abi) ⇒ Address

Create methods on this instance which match the definitions from a contract abi

Kind: instance method of Address
Returns: Address - reference to this object for chaining calls

address.loadAbi() ⇒ Promise

Load the abi publically associated with this address on etherest

Kind: instance method of Address
Returns: Promise - promise which resolves when the abi has been loaded with a reference to this address instance

address.urlEncode(suffix) ⇒ string

Gets the data for a request against an address encoded as a URL to send to etherest

Kind: instance method of Address
Returns: string - the encoded URL part to execute this query

address.call(path) ⇒ Promise

Executes a call against this address

Kind: instance method of Address
Returns: Promise - a promise which resolves when the call has been completed with the value returned

address.sendTransaction(path, options) ⇒ Promise

Sends a transaction to the etherest server

Kind: instance method of Address
Returns: Promise - a promise which resolves when the transaction has been submitted with an Ethereum txid

Query

Kind: global class

• Query
  • new Query([address], [method], params)
  • .param(value, [type]) ⇒ Query
  • .returns(type) ⇒ Query
  • .urlEncode() ⇒ string
  • .call(address) ⇒ Promise
  • .sendTransaction(address, options) ⇒ Promise

new Query(address, method, params)

Represents a single instance of an interaction with the blockchain, can be executed as a transaction or call

Returns: Query - new Query instance

query.param(value, type) ⇒ Query

Adds a param to the call/transaction to be sent

Kind: instance method of Query
Returns: Query - instance of this query to chain method calls from

query.returns(type) ⇒ Query

Set the return type for a query

Kind: instance method of Query
Returns: Query - instance of this query to chain method calls from

query.urlEncode() ⇒ string

Gets the data for this query encoded as a URL to send to etherest against a particular address

Kind: instance method of Query
Returns: string - the encoded URL part to execute this query

query.call(address) ⇒ Promise

Executes this query as a call

Kind: instance method of Query
Returns: Promise - a promise which resolves when the call has been completed with the value returned

query.sendTransaction(address, options) ⇒ Promise

Executes this query as a transaction

Kind: instance method of Query
Returns: Promise - a promise which resolves when the transaction has been submitted to the blockchain with a transaction id string