Skip to content

w3kit/etherest-client-js

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit

dist

dist

 
 

lib

lib

 
 

.babelrc

.babelrc

 
 

.gitignore

.gitignore

 
 

Readme.md

Readme.md

 
 

package.json

package.json

 
 

webpack.config.js

webpack.config.js

 
 

Repository files navigation

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:

Full Documentation

Etherest

Kind: global class

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

Param Type Description
[options] Object options to pass in to a new etherest instance
[options.server] string url for the api server to use, allows you to roll your own Etherest instance with our open source code
[options.apiKey] string api key to send with requests

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

Param Type Description
address string the address to instantiate the object with
[network] string network the address is associated with (ie main, ropsten etc)

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

Param Type Description
[options] Object custom options for the request (see request and browser-request for supported options)

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

Param Type Description
[path] string path to call relative to the base URL of the server

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

Param Type Description
[path] string path to send the transaction to relative to the base URL of the server
options Object options for the transaction, see options argument of Query.options

Address

Kind: global class

new Address(etherest, address, [network])

Represents an address on the blockchain

Returns: Address - new Address instance

Param Type Default Description
etherest Etherest etherest connection instance associated with this address
address string the ethereum address for this instance
[network] string "main" the network identifier this instance uses (ie main, ropsten, etc)

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

Param Type Description
method string name of the method which the query will call/sendTransaction against
params Array array of params which will be passed with this query, can take the form of an array of values or value/type pairs. See constructor of Query

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

Param Type Description
name string the name of the method to be used for this query
...param * params to be passed to the query

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

Param Type Description
name string the name of the method to be used for this query
params Array array of types of the params to be passed to this method as arguments
returns string the return type of the method

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

Param Type Description
name string the name of the method to be used for this query
params Array array of types of the params to be passed to this method as arguments
returns string the return type of the method

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

Param Type Description
name string the name of the method to be used for this query
params Array array of types of the params to be passed to this method as arguments

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

Param Type Description
abi Array application binary interface for this address

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

Param Type Description
suffix string additional string data to add to the end of the URL

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

Param Type Description
path string a relative path from this address to execute the call against

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

Param Type Description
path string path to send the transaction to relative to this address
options Object options for the transaction, see options argument of Query.options

Query

Kind: global class

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

Param Type Description
[address] Address address instance associated with this query
[method] string the contract method this query will target
params Array either a flat array of values which are the parameters or an array of type/value pairs
params[].value string the value of a param
params[].type string the type of a param

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

Param Type Description
value mixed the value of the parameter in this query
[type] string the type of the the parameter if we are not aware of it

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

Param Type Description
type string the type of the data returned by the query

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

Param Type Description
address Address the address to execute the call against, required if the query was not constructed with one

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

Param Type Default Description
address Address the address to send the transaction to, required if the query was not constructed with one
options Object options for the transaction
options.from string the address this transaction is being sent from
options.privateKey string the private key of the address this transaction is being sent from
[options.value] number 0 the amount ot eth to send with this transaction (1 = 1.0 Ether sent)
[options.gasPrice] number 20 the price to pay for gas for this transaction in gwei
[options.gasLimit] number 200000 the maximum amount of gas this transaction is allowed to use

About

ETHEREST.io client library for node.js/browsers

Resources

Readme
Activity
Custom properties

Stars

14 stars

Watchers

4 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages